FSK-Web Model Creation – FoodRisk-Labs

This manual gives an instruction how to create FSKX formatted harmonized models online as well as to run and download them afterwards.

1

After login to the FSK-Web Protected Area you will have access to the service for creating a FSKX compliant model online by using the workflow Online_Model_Creation.

Start the workflow by clicking on the Run button.

2

The workflow provides the opportunity to annotate and encode models in accordance with the harmonized metadata concepts and the harmonized information exchange format of the FSKX standards.

In general, the creation of a FSKX compliant model is based on the following information that should be provided by the model creator:

- metadata to annotate the model
- code for the mathematical model
- code for the visualization of the model result
- resource files (e.g. for datasets) if the script code requires them

According to the FSKX specifications, the model metadata cover the four main categories “General information”, “Scope”, “Data background” and “Model math”. For each of these main categories the metadata are presented in a structured form via different tabs.

Further information about the FSKX format including the FSKX guidance document are provided here.

Guidelines regarding the “Minimum Information Required to Annotate food safety Risk Assessment Models” (MIRARAM) can be found here.

Metadata fields, which are highlighted with asterisks (*), are mandatory fields with respect to the MIRARAM guidelines. Depending on the purpose for which the user wants to create the FSKX model, it might be possible that there is no need to fulfill the MIRARAM requirements. Therefore, it is not necessary to fill these metadata fields in order to run the workflow successfully for creating a new FSKX model.

Information for every metadata field is displayed when clicking on the corresponding i symbol. More details and definitions for all metadata fields, which are relevant for describing data and models, can be found here: Metadata_Master_Table.

To support harmonized annotation of the models, an online resource with controlled vocabularies for some metadata fields was established. If provided, a drop-down menu of the available controlled vocabularies will be shown after setting the cursor to the corresponding metadata field. The required term can be selected from the drop-down menu in order to appear in the metadata field. The terms used as controlled vocabularies are listed here: Controlled_Vocabularies_Master_Table.

3

Annotation of the model by providing appropriate metadata.

General Information → General

The field for the Identifier will be filled with an unambigous ID created automatically by the software tool.

Mandatory metadata fields: Name, Creation date, Rights and Language written in

4

General Information → Model Category

Mandatory metadata fields: Model class

5

General Information → Author

The author(s) is(are) the person(s) who generated the model code.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Author button (plus symbol).

The new author setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: Family Name

After saving the metadata setting the new entry will appear in the corresponding metadata list.

An entry in a metadata list can be modified or deleted supsequently by clicking on the corresponding Edith or Trash button. Also the order of the entries in a metadata list can be changed by clicking on the Move up or Move down buttons.

6

General Information → Creator

The creator(s) is(are) the person(s) who created the FSKX file for a model.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Creator button (plus symbol).

The new creator setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: Family Name, Email

After saving the metadata setting the new entry will appear in the corresponding metadata list.

7

General Information → Reference

Metadata about references to resources that the FSKX file is based on or related to can be provided here.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Reference button (plus symbol).

The new reference setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: DOI, Title

After saving the metadata setting the new entry will appear in the corresponding metadata list.

8

Scope → General

9

Scope → Product

Metadata about the product(s), for which the model applies, can be provided here.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Product button (plus symbol).

The new product setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: Name, Unit

After saving the metadata setting the new entry will appear in the corresponding metadata list.

10

Scope → Hazard

Metadata about the hazard(s), for which the model applies, can be provided here.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Hazard button (plus symbol).

The new hazard setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: Name

After saving the metadata setting the new entry will appear in the corresponding metadata list.

11

Scope → Population group

Metadata about the population group(s), for which the model applies, can be provided here.

In order to provide information, a set-up window for the metadata setting has to be opened by clicking on the Add a Population button (plus symbol).

The new population setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: Name

After saving the metadata setting the new entry will appear in the corresponding metadata list.

12

Data Background

The main category “Data background” provides different tabs to describe the data background of the model.

On the tab “Study” different metadata fields are available to give information for example about the design, measurement, technology and protocol used within a study. In addition, detailed metadata can be provided on further tabs like “Study sample”, “Dietary assessment method”, “Laboratory” and “Assay”.

13

Model math

On the different tabs information can be added regarding the fitting procedure applied on the data (Model math → General), the quality measure like the mean squared error (Model math → Quality measures), the equations used within the model code (Model math → Model equation) and the handling of left-censored data (Model math → Exposure).

14

Model math → Parameter

A FSKX compliant model allows to create and execute different simulation scenarios. Therefore, parameters have to be defined by the model creator. These parameters are used as variables within the model code. The parameters are classified as input (variable or constant) or output parameter. Each input parameter has an initial value, that should be provided by the model creator, to generate the default simulation.

In order to provide parameters, a set-up window for the metadata setting has to be opened by clicking on the Add a Parameter button (plus symbol).

The new parameter setting should be saved by clicking on the Save changes button.

Mandatory metadata fields: ID, Classification, Name, Unit, Data type, Value (for all parameters classified as “Input” and “Constant”)

After saving the metadata setting the new entry will appear in the corresponding metadata list.

The parameter IDs should be used as names of the variables within the model code.

The values of the parameters which are classified as “Input” can be adjusted in further simulation settings in order to create additional simulation scenarios.

The values of parameters which are classified as “Constant” cannot be modified regarding additional simulation scenarios.

The parameter data type is important for software tools interpreting the metadata and generate user interfaces for parameter input.

For all input parameters (variable and constant) an initial value has to be provided to generate the default simulation.

The value of the output parameters will be calculated during the model execution.

15

Model

The code for the mathematical model should be provided on the tab “Model”.

FSKX compliant models are based on script languages. For FSK-Lab v.2.0 (used in FSK-Web 1.0 ) the supported script languages are:

- R (BfR default: 3.4.4)
- Python 2 (BfR default: 2.7.13)
- Python 3 (BfR default: 3.5.3)

Functions to load packages of the script language and to read in resource files (e.g. datasets) should be provided within the model script.

Examples:

- R
  - library(utils)
  - read.table()
- Python
  - import pandas
  - pandas.read_table()

16

Visualization

The code for the visualization of the model result (a plot and/or a table) should be provided on the tab “Visualization”.

FSKX compliant models are based on script languages. For FSK-Lab v.2.0 (used in FSK-Web 1.0 ) the supported script languages are:

- R (BfR default: 3.4.4)
- Python 2 (BfR default: 2.7.13)
- Python 3 (BfR default: 3.5.3)

FSK-Lab v.2.0 (used in FSK-Web 1.0) supports the R package base plots and ggplot2 and the Python package matplotlib.pyplot for plotting or creating graphics.

17

Readme

The tab Readme should detail how the model code can be executed and which software tools and libraries (including version identifier) have to be installed within the required software. The tab should also be used to provide information for the end users helping them to understand the mode if there is no other suitable metadata field available for that.

18

Resources

On the tab Recources additional resource files such as datasets with different formats (e.g. .csv, .xlsx, .txt) can be uploaded if the script code requires them. The files can be uploaded by clicking on the Add Files button and selecting them from the file explorer.

After the provisioning of all necessary metadata, scripts and resource files is completed in order to create the model, the workflow can be continued by clicking on Next.

19

The workflow allows to create different simulation scenarios for the FSKX compliant model. The default simulation is based on the input parameters with their corresponding initial values.

The values of the variable input parameters can be adjusted in order to create additional simulation scenarios.

A new simulation setting can be added by clicking on the Add simulation button (plus symbol).

For each new simulation setting a name has to be given. The values of the parameters can be adjusted according to the scenario of interest. It is possible that a range of valid values is predefined for a parameter based on a minimum and a maximum value. Values of parameters which are classified as constant, cannot be modified. To support the user in designing a new simulation, further information of every parameter is displayed when clicking on the corresponding i symbol.

The newly created simulation setting has to be saved by clicking on the Save changes button.

Once one or more simulations have been created, the FSKX file of the model can be generated by clicking on the Next button.

Note

A FSKX compliant model allows to perform Monte Carlo simulation (reference for the example 10.5281/zenodo.4713653)

The following steps are required regarding the creation of a model using Monte Carlo simulation.

Define parameters for the number of iterations and for the domain of possible inputs (information how to create parameters see section 14)
Provide code in the model script to generate inputs randomly from a probability distribution over the defined domain (information how to design model code see section 15)
These inputs can be further used to perform deterministic computation of interest (information how to design model code see section 15)

20

The workflow automatically generates a report showing the main settings. The user can download the report (available in different formats .pdf, .docx, and .html) and the created FSKX model.

Note: Please be aware, that missing information might lead to errors. If that happens, go back via the Back button and correct the model.

This manual was created with support from EU and EFSA funding (GP/EFSA/AMU/2016/01) by BfR. It only reflects the BfR researchers views. Neither EFSA, EU nor BfR is responsible for any use of the website or the service.
 EFSA is an agency of the European Union