implement_model.md

A step-by-step introduction to implementing prediction models in VIPS

Tor-Einar Skog, Senior developer, NIBIO

Updated: 2022-08-30

What you will learn

This document describes how to implement and test a forecasting model that can be used on the VIPS platform.

Prerequisites

• You should be familiar with how the VIPS system works. It is recommended that you read the VIPS introduction
• You should have a basic understanding of the Java programming language.
• You should be somewhat familiar with NetBeans, or use another IDE that your’re familiar with, just bear in mind that some of the instructions may be irrelevant to you in that case.
• For model implementation in R or Python (currently not recommended), familiarity with the language at hand is of course recommended
• You need the library VIPSCommon (a file called VIPSCommon-2022.1.jar) somewhere on your local computer. You can clone and build it from here: https://gitlab.nibio.no/VIPS/VIPSCommon
• You need the example NetBeans project «FungusPilosusFlavisModel» somewhere on your local computer. You can clone it from our GitLab: https://gitlab.nibio.no/VIPS/test/funguspilosusflavismodel

Model design in VIPS

The structure of a model

A model is conceptually illustrated above. You have a set of input data in some form, you have the analysis/algorithms happening inside the model, and the model returns a set of results. In VIPS, certain design requirements must be met:

• The model must be programmed in Java or another language that can run on the Java Virtual Machine. This includes R and Python (only 2.7, not recommended)
• The model must implement an interface (a design contract)
• The model must be packaged as a JAR (Java Archive) file
• The input data must be in a specific format (details below)
• Results must be returned in a specific format (details below)
• The model must provide its own description and usage information in at least English and aditionally in any preferred language

When a model meets these requirements, it can be deployed to the VIPS Core runtime server and be made available without any more configuration. The model can be called over HTTP/REST from any authenticated client on the Internet. In order to set up batch jobs (running at regular intervals) in the VIPS admin, some configuration classes need to be added to the VIPSLogic system, which acts as an authenticated client.

Developing a model

What you need to develop a VIPS model is:

• A decent coding environment (IDE) like NetBeans, Eclipse or IntelliJ.
• A library of VIPS classes called VIPSCommon.jar
• A testing framework like Junit. This is normally bundled with your IDE (see above)

The normal workflow is that you have some correctly formatted (see other documentation) weather data in a file that you put on the project’s classpath, you mix this with the other configuration data and develop the model based on these input data. You must have one main class that implements the Model interface, which is available in the VIPSCommon.jar library. The test framework can be used to test single methods that are part of the algorithms or you can test the complete model.

When you’re happy with how the model works you can test deploy it to the VIPSCore server (TODO: Document this)

Implementing a forecasting model step-by-step

In this project, we are going to implement a forecasting model for a virtual fungus called «Fungus pilosus flavis» (please bear with me, any phytopatologists who might read this). Let's say that it there is a forecasting model for it that states that