BioMA Spatial Tutorial - Agri4Cast ToolBoxagri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/PDF_Documents/... · Introducing BioMA Spatial - Tutorial 7 BioMA Spatial - Tutorial

Tutorial

Running a Modelling Solution

Introducing BioMA Spatial

2 Introducing BioMA Spatial - Tutorial

Copyright

© European Union, 1995‐2018

Reproduction is authorised, provided the source is acknowledged, save where otherwise stated.

Where prior permission must be obtained for the reproduction or use of textual and multimedia information (sound, images, software, etc.), such permission shall cancel the above‐mentioned general permission and shall clearly indicate any restrictions on use.

Disclaimer

On any of the MARS pages you may find reference to a certain software package, a particular contractor, or group of contractors, the use of one or another sensor product, etc. In all cases, unless specifically stated, this does not indicate any preference of the Commission for that particular product, party or parties. When relevant, we include links to pages that give you more information about the references.

Feel free to contact us, in case you need additional explanations or information.

Release Issue Date Authors

1.0.6 7 September 2018 G.Ferrari/D.Fumagalli

5

Contents

BioMA Spatial - Tutorial: Running a model simulation 3

Step 1 ‐ Setting up BioMA Spatial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4To install the drivers to connect to the portable database:. . . . . . . . . . . . . . . . . . . . . . 4To check the Windows settings of your PC: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4To install the BioMA Spatial application and the example files: . . . . . . . . . . . . . . . . 4To install the modelling solution packages: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5To deploy the regional settings:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6To deploy the simulation control: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Step 2 ‐ Selecting and configuring the modelling solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8To select the modelling solution:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8To configure the modelling solution: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Step 3 ‐ Setting the component’s parameters and validating the configuration . . . . . . . . . . . .12To set the model parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12To validate your configuration: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Step 4 ‐ Setting the GDD persister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14To set the GDD persister: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Step 5 ‐ Running, saving, and reloading the model’s simulation . . . . . . . . . . . . . . . . . . . . . . . .15To run the simulation: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15To save the simulation: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15To load the saved configuration: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Step 6 ‐ Launching GDD and viewing the simulation results. . . . . . . . . . . . . . . . . . . . . . . . . . . .17To launch GDD and view the simulation results: . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Step 7 ‐ Available resources on BioMA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21To access and browse the BioMA Portal: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

CONTENTS


Introducing BioMA Spatial - Tutorial 7

BioMA Spatial - TutorialRunning a model simulation

Welcome to the BioMA Spatial tutorial!

This tutorial will help you understand how to select a modelling solution, how to configure it, and how to run a model simulation.

Please, note that this tutorial provides an example for you to perform a complete round‐trip of BioMA Spatial.

In particular, you will run a simulation for rice crops, over a year, and for one location using the WARM modelling solution. WARM (acronym of Water Accounting Rice Model) is implemented within the BioMA platform and is used for the rice growth monitoring and yield forecasting.

We've provided everything you need to successfully complete your first simulation's running.

The tutorial has been organized into the following steps:

Steps

“Step 1 - Setting up BioMA Spatial” on page 8

“Step 2 - Selecting and configuring the modelling solution” on page 13

“Step 3 - Setting the component’s parameters and validating the configuration” on page 17

“Step 4 - Setting the GDD persister” on page 19

“Step 5 - Running, saving, and reloading the model’s simulation” on page 20

“Step 6 - Launching GDD and viewing the simulation results” on page 22

“Step 7 - Available resources on BioMA” on page 26

1 – BIOMA SPATIAL - TUTORIAL RUNNING A MODEL SIMULATION


Step 1 - Setting up BioMA SpatialThis lesson teaches you how to complete the new setup procedure for BioMA Spatial. All steps are mandatory.

In this exercise you are going:

• To install the drivers for database connection

• To check the Windows settings of your PC

• To install the BioMA Spatial application and the example files:

• To install the modelling solution packages:

• To deploy the regional settings:

• To deploy the simulation control:

• To deploy the agromanagement provider:

• To deploy the weather data provider:

To install the drivers to connect to the portable database:

1 Go to the Microsoft Download Center

2 Click Download.

3 In the popup, select Run, then specify an extraction location on your computer.

Please, note that BioMA can connect to different data sources but for the aim of the tutorial we use a Microsoft SQL server compact portable database.

To check the Windows settings of your PC:

Ensure that the settings of your PC are set as follows:

1 Access the Windows Control Panel (click the Start button, then select Control Panel > Clock, Language, and Region > Region and Language).

2 In the Region and Language window, click Additional settings.

3 Be sure that the Decimal symbol is set to “point” (.).

To install the BioMA Spatial application and the example files:

In this step you will download the files that contain the installation package and the sample data that are needed to complete the tutorial.

http://www.microsoft.com/it-it/download/details.aspx?id=5783

9

STEP 1 - SETTING UP BIOMA SPATIAL

Introducing BioMA Spatial - Tutorial

Download and setup the BioMASpatial setup file:

1 Download the BiomaSpatialSetup.exe file from this URL: http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/BiomaSpatialSetup.exe.

Depending on your security settings, you will be requested (one or more times) to confirm the setup execution.

2 Click Run at the bottom of the page and then Install when requested.

3 At the end, BioMA Spatial will automatically open. Furthermore, a new shortcut to BioMA Spatial will be created on your desktop.

4 Download the following packages and unzip them:

‐ WARMPackage.zip ‐ The WARM modelling solution package, from URL: http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/WARMPackage.zip

‐ BiomaSpatialTutorial2018.zip ‐ The regional settings file, and the CSV file to be used as source data, from URL: http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/BiomaSpatialTutorial2018.zip

To install the modelling solution packages:

In this step you will install the WARM modelling solution that we have provided.

1 Open BioMA Spatial and, from the toolbar, select Settings > Libraries management and regional settings.

2 Click Choose a package to deploy.

Troubleshooting access problems (if any):

If an error is displayed regarding missing grants on the installation folder (like “Access to the path X is denied”), you must change the security properties of the folder and its subfolders. To do that:

• Go to the BioMA setup folder, right-click it, and then select Properties.

• Select the Security tab and click the Edit button.

• Under Group or user names, select the current user or Users.

• Allow to the user(s) the Full control permission, click Apply, and then Ok.

• Launch Bioma Spatial by clicking the BioMA icon that was created on your desktop after the installation process.

http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/BiomaSpatialSetup.exe



http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/WARMPackage.zip

http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/WARMPackage.zip

http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/BiomaSpatialTutorial2018.zip

http://agri4cast.jrc.ec.europa.eu/DataPortal/Resource_Files/Software/biomaspatial/BiomaSpatialTutorial2018.zip



3 In the BioMA installation folder that opens, go to the Packages folder.

4 Browse to locate the WARMPackage.bpkg file that you downloaded from the Web Portal, then click Open.

5 Check Deploy as modeling solution, then click Deploy. BioMA Spatial will restart and will now include the modelling solution package you deployed.

To deploy the regional settings:

In this step you, you will deploy the regional settings, that is, you will install the files that are required to actually run and view the simulation (mapping files, crop masks, configuration files, portable databases, and so forth).

1 Open BioMa Spatial and, from the toolbar, select Settings > Libraries management and regional settings.

2 At the bottom of the window, click Add.

3 In the BioMA installation folder that opens, select the .brs file (BiomaSpatialTutorial2018.brs) that you downloaded from the Web Portal.

4 Click Ok when prompted, then wait for the unzip process to complete.

5 The message Regional settings unzipped will be displayed including some potential warnings saying that some dlls are already loaded in Bioma and cannot be overwritten. In most cases you can ignore these warnings.

6 Click Ok to restart the application.

To deploy the simulation control:

In this step, you will deploy a library containing the code for managing the simulation cycle.

Note:

Since the installation folder has a very long name and it depends from your operating system, to facilitate users, the folder will open automatically.

Note:

This is an example of deployment of a library, which contains new functionalities that are not provided with application’s core.

11

STEP 1 - SETTING UP BIOMA SPATIAL


Do the following:

1 From the BioMA Spatial toolbar, select Settings > Libraries management and regional settings.

2 Click the Choose a library to deploy button.

3 In the BioMA Spatial installation folder that opens, go to the Packages folder, browse to locate the EC.JRC.MARS.SimulationControl.CompositionLayerLibrary.dll file, and then click Open.

4 Click Deploy and confirm it.

BioMA Spatial will be restarted and will now include the newly deployed library.

To deploy the agromanagement provider:

In this step, you will deploy a library containing the code for managing the agromanagement events (sowing and harvest).


Do the following:

1 From the BioMA Spatial menu, select Settings > Libraries management and regional settings.


3 In the BioMA Spatial installation folder that opens, go to the Packages folder, browse to locate the JRC.IPSC.MARS.CommonAgromanagementProviders.dll file, and then click Open.



To deploy the weather data provider:

In this step, you will deploy a library containing the code for retrieving the weather data from CSV files.

Note:




Do the following:

1 From the BioMA Spatial menu, select Settings > Libraries management and regional settings.


3 In the BioMA Spatial installation folder that opens, go to the Packages folder, browse to locate the EC.JRC.MARS.CSVWeatherProviders.dll, and click Open.



Note:


You are now ready to start working with BioMA Spatial!

13

STEP 2 - SELECTING AND CONFIGURING THE MODELLING SOLUTION


Step 2 - Selecting and configuring the modelling solutionIn this exercise you will select and configure the WARM modelling solution, which you installed in the Lesson 1.

To select the modelling solution:

1 In the BioMA window, select the Main page tab:

2 In the Modeling solution configuration pane, next to the Modelling Solution item, double‐click under Value to open the drop‐down list:

3 From the list of available modelling solutions, choose WARM.

To configure the modelling solution:

In this step you will set the Configuration Items that are displayed after selecting the modelling solution. These items allow determining how you want to run the simulation:



The Value column contains the drop‐down lists with all possible Configuration Items’ settings: by clicking a row, the drop‐down is made available.

1 Set the Weather Configuration to CSV single file. (Please, configure this item before configuring the Simulation Configuration so as to make available the years that you can select). Two new items are displayed:

(Note that the weather data can come from different type of database, but in this tutorial, for convenience, we use CSV files).

‐ WeatherCSVFilePath ‐ Click the ellipsis button as shown above, then navigate to the Spatial main installation folder (e.g., C:\Program Files (x86)\JRC\BiomaSpatial), and locate the TestCsvWeatherData.csv file.

15

STEP 2 - SELECTING AND CONFIGURING THE MODELLING SOLUTION


‐ GridDataCSVFilePath ‐ Repeat the same operation, but select the TestCsvGridData.csv file.

This way, you tell BioMA Spatial to use these CSV files as the source weather data.

2 Set the Simulation Configuration to Daily steps with start year. Four new items are displayed:

‐ Start Year ‐ From the dropdown list, select 2010.

‐ Start Year Doy ‐ Enter 1. This is the day of the start year.

‐ Number of Years ‐ Enter 1.

‐ Location ID ‐ From the dropdown list, select 76110. This identifies a location, which is a 25 km cell located in region you are running the simulation for. The location of our example is in Lombardia, North Italy.

3 The next three items (Weather Switch Calculate Evapotranspiration, VPD, and Humidity) can be set to False as these are already included within the CSV files that you loaded in step 2. So, there is no need for recalculation.

4 Set the Agromanagement Configuration: from the dropdown list, select Load rules from agromanagement file. A new item is displayed:

‐ Agromangement file ‐ Click the ellipsis button to display the following popup:

‐ Click Change agromanagement file.

‐ Browse to the BioMA Spatial installation folder > ParametersFiles folder, and open the AgromanagementTestWarm.xml file.



‐ Click Close to return to BioMA Spatial.

This is the XML agromanagement file that defines which type of rice you are simulating, as well as both the sowing and the harvest time.

5 Set all the other items to False with the exception of the LeafWetness Component, which must be set to None. These are settings of the WARM modelling solution that, for the sake of this tutorial, we will not consider as this would imply an additional number of configurations.

6 Set the Check preconditions item to Disable.

Note

It is possible to customize many agromanagement aspects, however, for the sake of this tutorial, we propose to use a default set of agromanagement rules that are saved in a XML file.

For further information, see Agromanagement module.

You have just configured your modelling solution.

You can now go ahead and edit the parameters!

http://bioma.jrc.ec.europa.eu/components/Default.aspx?productname=AgroManagement

17

STEP 3 - SETTING THE COMPONENT’S PARAMETERS AND VALIDATING THE CONFIGURATION


Step 3 - Setting the component’s parameters and validating the configuration

In this exercise, you will set the component’s parameters, that is, you will tell BioMA Spatial which XML file to use. Each component has an associated file that contains the relevant parameters; this might be a database, as well.

Then, you will validate the modelling solution’s configuration.

To set the model parameters:

1 In the right side of the BioMA Spatial window, click the Show button next to Component to display the WARM parameters:

2 From the Parameters reader dropdown list, select MPE parameters from XML as shown above.

3 In the Xml file path field that is displayed, click the ellipsis button, browse to the ParameterFiles folder, then select the Parameters WARM. xml file. This way, you tell Spatial to use the values that are stored in this file, as the parameters’ values.

4 The Parameters key field is automatically set to Rice.



5 Repeat the same operation (1 to 3) for the WARMLimited parameters.

Note: The two components WARM parameters and WARMLimited parameters are two copies of the WARM model that calculate two different results: while WARM calculates the potential rice growth, WARMLimited calculates the growth, as well, but limited by external factors, such as diseases. To obtain both results, you must set the same parameters for both components.

To validate your configuration:

1 In the BioMA Spatial toolbar, click Validate values to validate the configuration.

2 The green message Validation succeeded will be displayed to tell you that all the values were correctly set.

If any error is detected during validation, a popup is displayed with a description (missing/wrong field values) along with the Error during validation message.

You have just completed and validated the configuration.

19

STEP 4 - SETTING THE GDD PERSISTER


Step 4 - Setting the GDD persisterBioMA Spatial allows saving the simulation configuration in a persistence format using the Persisters configuration function.

Configurations can be saved in a text file, in a database, in a XML file, or in Graphic Data Display (GDD) format. Users can also configure their own persisters.

In this tutorial, we will configure the Persister for GDD, so as to be able to retrieve the simulation results using the GDD BioMA plugin.

The GDD plugin allows to analyze the results both in tables and in several graph forms (as it is explained in “Step 6 ‐ Launching GDD and viewing the simulation results” on page 22).

To set the GDD persister:

1 Do one of the following:

‐ In the BioMA Spatial menu bar, click the Settings button and then select Model output storing from the dropdown menu.

‐ In the Simulation panel, at the bottom‐right of the BioMA window, click Model output storing.

2 The Model output storing window is displayed.

3 Click the Value column next to Persister to display the dropdown list.

4 Make sure that the Keep data in memory for GDD option is selected, otherwise, select it.

5 Click Close to return to the BioMA Spatial main page.



Step 5 - Running, saving, and reloading the model’s simulation

In this exercise, you will finally run the simulation and then you will save the configuration into a file, so that you can reuse it.

To run the simulation:

1 In the Simulation area at the bottom‐right of the BioMA window, enter a Simulation description, such as Rice simulation for Spatial Tutorial:

2 In the BioMA Spatial menu bar, click (Start the simulation) to launch the simulation.

3 Ensure that the End of the simulation message is displayed in the Log window at the bottom‐left, and that no errors are detected.

To save the simulation:

1 In the BioMA Spatial menu bar, click (Save a configuration file).

2 In the Save a configuration file window that is displayed, enter a meaningful File name (e.g., BioMA Tutorial2.bcf).

3 Click Save. The file will be saved as a BioMA configuration file (.*BCF file).

Note: By default the file will be saved in the BiomaConfigFiles folder, but you can choose another directory.

To load the saved configuration:

After saving a configuration, you can reload it within Spatial.

1 In the BioMA Spatial menu bar, click (Open a configuration file).

21

STEP 5 - RUNNING, SAVING, AND RELOADING THE MODEL’S SIMULATION


2 In the Open a Bioma configuration file (.bcf) window that is displayed, select the BioMA Tutorial2.bcf file that you saved in the previous step.

As a result, the configuration will be displayed, with all your settings.

Tip:

You may practice and reload another previously done configuration file (e.g., BioMA Tutorial.bcf), which should be equal to the one you developed in this tutorial. Practice reloading both and comparing them.

You have successfully run a model simulation.

Now, you can view the results with a graphic viewer.



Step 6 - Launching GDD and viewing the simulation results

In “Step 4 ‐ Setting the GDD persister”, we have set the persister that allows retrieving the simulation’s results with the Graphic Data Display.

In this exercise, you will launch the GDD (Graphic Data Display) BioMA plugin to retrieve and view the results of the simulation, both in a table and as a graph.

To launch GDD and view the simulation results:

1 Once you have run the simulation (Lesson 5), click the GDD button in the BioMA toolbar to analyze the results:

23

STEP 6 - LAUNCHING GDD AND VIEWING THE SIMULATION RESULTS


2 From the Component dropdown list (which contains the models’ outputs) at the top of the Data Viewer window, select Crop summary decade.

This shows the crop simulation results saved for 10 days, in a tabular view:

The data are displayed in the table according to the Component you select. In this case, each row is a decade, and records are grouped by the Location ID (Grid column) that you selected in Lesson 2 (76110).

3 To view the same output as a graph, select the Graph Var vs Time tab. This view allows setting the time period and the variable, as well as providing some graph options.

4 From the Component dropdown list, at the bottom of the tab, select WARM1_States (it shows the states of the plant, day by day), and, as



the Variable, select AbovegroundBiomass (that is, the biomass of the plant, one of the most significant variables):

5 Click Add selected variable and then the Draw button. As a result, a graph will be displayed:

25

STEP 6 - LAUNCHING GDD AND VIEWING THE SIMULATION RESULTS


6 To change the type of graph (e.g., to display symbols rather than lines), use the available options, as shown in the screenshot.

7 Click Draw again to re‐draw the graph based on your selections.

8 To export the graph as an image, click the Export graph button, select the image format (JPG, GIF, PNG, or BMP), specify a File name and then click Save.

Tip:

GDD has its own Help: to access it, click the Info button at the bottom of the page and then click Help.

You have completed the tutorial.

Go to the next Lesson and see the available resources on BioMA.



Step 7 - Available resources on BioMAIn this lesson, you will be given a quick look of how you can take advantage of the Web‐based available resources via the BioMA Portal.

To access and browse the BioMA Portal:

The Web‐based BioMA Portal has been built in order to provide an overview of the BioMA Framework, as well as the links to all tools/documentation that exist for BioMA.

1 Go to http://bioma.jrc.ec.europa.eu/ to display the following:

http://bioma.jrc.ec.europa.eu/

27

STEP 7 - AVAILABLE RESOURCES ON BIOMA


2 Navigate to the portal pages to access the step‐by‐step BioMA Tutorials (such as this one) and all the available documentation.

In particular, the Documentation page provides the link to the PDF and Online versions of all the existing Bioma applications’ User Guides:

