From 4813406e1c1222c75b31b350be769a19c3d473ea Mon Sep 17 00:00:00 2001
From: Tor-Einar Skog <tor-einar.skog@nibio.no>
Date: Thu, 23 Feb 2023 09:01:53 +0100
Subject: [PATCH] Added info for input data an result data
---
input_data.md | 39 +++++++++++++++++++++++++++-
model_development_java.md | 5 ++++
model_development_python.md | 5 ++++
model_implementation.md | 2 +-
result_data.md | 51 +++++++++++++++++++++++++++++++++++++
weather_data.md | 8 ++++--
6 files changed, 106 insertions(+), 4 deletions(-)
diff --git a/input_data.md b/input_data.md
index 1f9a61d..df1e760 100644
--- a/input_data.md
+++ b/input_data.md
@@ -1,3 +1,40 @@
<img src="illustrations/vipslogo_512.png" alt="VIPS Logo" height="250"/>
-# VIPS Model input data
\ No newline at end of file
+# VIPS Model input data
+
+Tor-Einar Skog, Senior developer, NIBIO
+
+Updated: 2023-02-23
+
+
+Below is a minimum example of VIPS result data.
+
+**---> TODO create Json schema <---**
+
+```json
+{
+ modelId:'REFERENCEM',
+ configParameters: {
+ 'sowingDate': '2022-03-01',
+ 'observations': [
+ {'timeMeasured': '2015-03-01T00:00:00+01:00', 'elementMeasurementTypeId': 'TM', 'logIntervalId': '2', 'value': '1.41025'},
+ {'timeMeasured': '2015-03-02T00:00:00+01:00', 'elementMeasurementTypeId': 'TM', 'logIntervalId': '2', 'value': '2.87608333333333'},
+ {'timeMeasured': '2015-03-03T00:00:00+01:00', 'elementMeasurementTypeId': 'TM', 'logIntervalId': '2', 'value': '1.00854166666667'},
+ {'timeMeasured': '2015-03-04T00:00:00+01:00', 'elementMeasurementTypeId': 'TM', 'logIntervalId': '2', 'value': '-1.44675'}
+ ]
+ }
+}
+```
+
+## modelId
+This is the 10-character unique id for the specific model
+
+## configParameters
+Here are the input data, which are free-form, but by convention weather data are to be found in the `observations` property, and they must follow the [VIPS weather data format](./weather_data.md). Here, we also have a `sowingDate` that this specific model requires.
+
+## Usage in a VIPS model
+### Java
+In [VIPSCommon](https://gitlab.nibio.no/VIPS/VIPSCommon), there is a `ModelConfiguration` class that encapsulates all the necessary functionality.
+### Python
+In [VIPSCore-Python-Common](https://gitlab.nibio.no/VIPS/vipscore-python-common) there is a `ModelConfiguration` class in `entities.py` that encapsulates all the necessary functionality.
+
diff --git a/model_development_java.md b/model_development_java.md
index 43e6e57..b9db277 100644
--- a/model_development_java.md
+++ b/model_development_java.md
@@ -1,6 +1,11 @@
<img src="illustrations/vipslogo_512.png" alt="VIPS Logo" height="250"/>
# Developing a model using Java
+
+Tor-Einar Skog, Senior developer, NIBIO
+
+Updated: 2023-02-23
+
This page builds on [A step-by-step introduction to implementing prediction models in VIPS](model_implementation.md)
What you need to develop a VIPS model is:
diff --git a/model_development_python.md b/model_development_python.md
index 260d3a8..3ea74f7 100644
--- a/model_development_python.md
+++ b/model_development_python.md
@@ -1,6 +1,11 @@
<img src="illustrations/vipslogo_512.png" alt="VIPS Logo" height="250"/>
# Developing a model using Python
+
+Tor-Einar Skog, Senior developer, NIBIO
+
+Updated: 2023-02-23
+
This page builds on [A step-by-step introduction to implementing prediction models in VIPS](model_implementation.md)
## Preparations
diff --git a/model_implementation.md b/model_implementation.md
index 4666376..4d503f1 100644
--- a/model_implementation.md
+++ b/model_implementation.md
@@ -4,7 +4,7 @@
Tor-Einar Skog, Senior developer, NIBIO
-Updated: 2023-02-21
+Updated: 2023-02-23
## What you will learn
This document describes how to implement and test a forecasting model
diff --git a/result_data.md b/result_data.md
index adcfd25..b96c879 100644
--- a/result_data.md
+++ b/result_data.md
@@ -1,3 +1,54 @@
<img src="illustrations/vipslogo_512.png" alt="VIPS Logo" height="250"/>
# Specification of VIPS model result data
+Tor-Einar Skog, Senior developer, NIBIO
+
+Updated: 2023-02-23
+
+
+Below is a minimum example of VIPS result data.
+
+**---> TODO create Json schema <---**
+
+```json
+[
+ {
+ "validTimeStart": "2016-09-29T05:00:00+00:00",
+ "validTimeEnd": null,
+ "validGeometry": null,
+ "warningStatus": 2,
+ "allValues": "{\"FUNGUSPILO.CONTROLLED_INFECTION_RISK\": \"10\"}"
+ },
+ {
+ "validTimeStart": "2016-09-29T06:00:00+00:00",
+ "validTimeEnd": null,
+ "validGeometry": null,
+ "warningStatus": 2,
+ "allValues": "{\"FUNGUSPILO.CONTROLLED_INFECTION_RISK\": \"12\"}"
+ }
+]
+
+```
+
+## Values
+The result values are stored as Json inside the `allValues` property, as Json string. It's a string so that we can store it freely in a database, but now that PostgreSQL has support for Json contents, this can be fixed (TODO).
+
+## warningStatus
+This property represents the "Traffic lights" of VIPS, and the codes are to be interpreted as follows:
+
+* 0 = No result. Could be due to several reasons, e.g that the season has not started or is already over
+* 1 = Missing data. The model is running, but lacks the required input data to perform the calculations. This could be missing weather data or that the model requires a field observation at a certain point in the growing season
+* 2 = No risk (Green traffic light)
+* 3 = Some risk (Yellow traffic light)
+* 4 = High risk of infection (Red traffic light)
+
+Exactly how to interpret the traffic lights should be provided in each model's warning status interpretation metadata method
+
+## Metadata
+The other properties are describing the time and space of the prediction. `validTimeStart` is the only mandatory of the three properties. If you add `validTimeEnd`, the object describes a period rather than a point in time. `validGeometry` describes where the prediction is valid. This is in [GeoJson](https://geojson.org/) format, so it could be any GIS entity, such as point, polygon, multipolygon.
+
+## Usage in a VIPS model
+### Java
+In [VIPSCommon](https://gitlab.nibio.no/VIPS/VIPSCommon), there is a `Result` interface and a `ResultImpl` class that encapsulates all the necessary functionality.
+### Python
+In [VIPSCore-Python-Common](https://gitlab.nibio.no/VIPS/vipscore-python-common) there is a `Result` class in `entities.py` that encapsulates all the necessary functionality.
\ No newline at end of file
diff --git a/weather_data.md b/weather_data.md
index 57f69e8..5e2bde3 100644
--- a/weather_data.md
+++ b/weather_data.md
@@ -2,6 +2,10 @@
# Specification of external weather data source for VIPS
+Tor-Einar Skog, Senior developer, NIBIO
+
+Updated: 2023-02-23
+
## Preface
This is a description of how a weather data provider can make weather data available for forecasting models running in VIPS, NIBIO's system for forecasting agricultural pests and diseases.
@@ -49,7 +53,7 @@ Explanation:
All weather stations (or measuring points) in the same external weather data source must have a uniform URL pattern. E.g.:
```
-https://lmt.nibio.no/services//rest/vips/getdata/?weatherStationId=[weatherStationId]&elementMeasurementTypes[]=TM&elementMeasurementTypes[]=RR&elementMeasurementTypes[]=UM&logInterval=1h&startDate=2019-05-01&startTime=00&endDate=2019-05-20&endTime=23&timeZone=Europe/Oslo&elementMeasurementTypes[]=BT
+https://lmt.nibio.no/services/rest/vips/getdata/?weatherStationId=[weatherStationId]&elementMeasurementTypes[]=TM&elementMeasurementTypes[]=RR&elementMeasurementTypes[]=UM&logInterval=1h&startDate=2019-05-01&startTime=00&endDate=2019-05-20&endTime=23&timeZone=Europe/Oslo&elementMeasurementTypes[]=BT
```
The `[weatherStationId]` is a placeholder for the unique identificator for a particular weather station. It need not be numerical (although that is recommended), but it must be able to easily pass on as part of a URL.
@@ -100,6 +104,6 @@ Due to a wish to standardize the names of the codes using international standard
|Organization|URL pattern|Contact person|
|------------|-----------|--------------|
-|NIBIO|http://lmt.nibio.no/agrometbase/export/getVIPS3JSONWeatherData.php?weatherStationId=[weatherStationId]|[Tor-Einar Skog](https://nibio.no/ansatte/tor-einar-skog)|
+|NIBIO|https://lmt.nibio.no/services/rest/vips/getdata/?weatherStationId=[weatherStationId]|[Tor-Einar Skog](https://nibio.no/ansatte/tor-einar-skog)|
|Swedish University of Agricultural Sciences|http://www.ffe.slu.se/lm/json/downloadJS.cfm?weatherStationID=[weatherStationId]|[LantMet](mailto:lantmet@slu.se)|
\ No newline at end of file
--
GitLab