FAO
Research, Extension and Training Division
Environment and Natural Resources Service (SDRN)
Agrometeorology Group
BAgS
Beginning of Agricultural Season
User’s Manual
Pierre Mahau
University of Louvain
Computer Science
Research and Development
2004
BAgS – User’s Manual - 2004
Abstract
This paper summarizes the results of three month spent at the FAO Headquarters from
February to May 2004 in the Agrometeorology Group of the Environment and Natural
Resources Service (SDRN), Research, Extension and Training Division, under the supervision
of René Gommes.
Crop of vegetation phenology is important for climate change and seasons estimation. It
allows the study and the modelling of the vegetation growth. BAgS (for Beginning of the
Agricultural Season) is a tool that use time series image to qualify and quantify the variations
of NDVI or other variables such as rainfall, and to determine significant parameters of the
agricultural seasons.
2
BAgS – User’s Manual - 2004
3
Introduction
AMS constitutes a consolidation of several packages developed by SDRN-Agrometeorology
Group. It is used by most of National Early Warning Units for Food Security, and by worldwide agricultural applications centres. It represents an essential tool for agrometeorological
risk analysis and for regional crop yield forecasting.
BAgS has been designed as a module for integration into AgroMetShell version 2.00. The
BAgS user-interface is called directly by the AMS menu and the results are stored in IDA
images that are full compatible with the WinDisp software.
Wrote as “dll” in Visual C++, BAgS can therefore be called from any Windows application or as
stand-alone application.
BAgS has been designed for:
- Reading a set of NDVI or rainfall images at the 10-day or monthly time step. The images
cover one complete agricultural season or the beginning of a season. Their size and projection
are identical.
- For a user-defined pixel, extracting and displaying time-series values.
- Fitting a curve through the time-series and determine the characteristics of the season, based
on a user-provided earliest beginning and latest end: date of beginning, lowest value, date
when maximum is reached, maximum value, date of end and value at end. Elementary
differences are also computed, such as Maximum-Minimum.
- Saving results maps in WinDisp format for all the characteristics of the season defined
above.
BAgS – User’s Manual - 2004
4
Method
After the IDA images has been loaded, each pixel from the same coordinate is extracted from
the time-series images and is stored in a time-series vector that is used for the rest of the
treatment. The cloud and water corresponding pixels are replaced by a missing value.
Image ARTEMIS – NDVI – Sénégal, Janvier 2003
The treatment of the temporal series consists in several steps:
Smoothing:
The signal is smoothed with a “4253H smoother, twice” wich consists of a running median of
4, then 2, then 5, then 3, followed by Hanning. Hanning is a running weighted average with
weights ¼, ½, ¼. The result of this smoothing is then reroughed by computing residuals,
applying the same smoother to them and adding the result to the smooth of the 1st pass.
BAgS – User’s Manual - 2004
5
Peak detection and season quantification:
A deterministic method is used that consists on a walk on the first numerical derivative for
detects and isolates peaks.
When the slope becomes positive, an onset is interpolated. By the way, the maximum is
interpolated near the first point where the slope becomes negative.
In order to avoid detecting a false peak, some criteria must be fixed by the user:
-
The range date within a complete season should be found.
-
The minimum delta amplitude between the baseline and the maximum.
-
The minimum growth time (elapsed time since the onset)
Then, the size (duration) of the plateau is measured from a portion (in %) of the deltaamplitude. A threshold is calculated as cut-off level. Since the nearest points to the beginning
and to the end of the plateau have been founded, the corresponding dates are interpolated
(second degree polynomial fit).
NDVI
Beginning of
platteau
End of
platteau
delta_amp
max_amp
Base line
onset_time
t0
Growing
time
t
BAgS – User’s Manual - 2004
6
Model adjustment:
In order to estimate the missing part of the season, a Gaussian model has been implemented in
the program.
y  a.e
  ( x b ) 2

 2c 2





Model fitting is made by the Least Square Method.
Senegal 2003 NDVI Time Series (Spot-Vega)
7,00E-01
6,00E-01
5,00E-01
Original
NDVI
4,00E-01
Smooth
3,00E-01
Model (Gauss)
2,00E-01
1,00E-01
0,00E+00
0
50
100
150
200
250
300
350
400
Time (days)
Time series (NDVI) computed from ARTEMIS images – Sénégal 2003
BAgS – User’s Manual - 2004
7
The program
Overview:
Parameters
and
Image n
Image 5
Image 4
Image 3
Image 2
Image 1
IDA
options
Process
all points
Results
IDA
Input:
The data input consists of a text file that contains the parameters and a set of IDA images that
must have exactly the same header and the same size. This because BAgS stores the first map
header that will be used for the whole set of images.
Process:
BAgS reads each IDA image in the same order as provided by the user in the list, store the
first header and compare it to the rest of the series. That because BAgS cannot work with
heterogenic series. The pixel part of all maps is also loaded in a three-dimensional matrix.
Then, pixel by pixel, a time-series vector is extracted from the three-dimensional matrix and
treated as explained in the method section of this paper.
Output:
BAgS results are stored in IDA images with the same format as the input. In the header of the
IDA image results, the values of slope and intercept are modified if needed. For date results,
i.e., the slope becomes 1.0 and the intercept is fixed by the “SeasonBeginMin” user provided
variable.
The program uses the “GenericFileName” user provided variable as prefix, immediately
followed by the specific name of the result as postfix for creating the name of the IDA maps.
BAgS – User’s Manual - 2004
For example: if GenericFname is “Sen2003”, the Maximum level wills be stored in a map
named “Sen2003MaxLevel.img”.
The list off the IDA maps results that BAgS produces is:
- BaseLine
- OnsetLevel
- OnsetTime
- MaxLevel
- MaxTime
- PlateauLevel
- PlateauStartTime
- PlateauEndTime
- SeasonEndLevel
- SeasonEndTime
8
BAgS – User’s Manual - 2004
Parameters and options
The options and user provided variables are stored in a text file (ASCII) that BAgS parses at
start up. These parameters are listed here:
List of IDA images:
This is the name of the text file that contains the list of the IDA images files names of the
series. For a complete description of this file, see below.
Images directory:
This is the path where the images specified in the list are located.
Working directory:
This is the path where the result images will be stored.
Generic file name:
This string is used as prefix to name each result image. For example: if Cameroun2000 is the
“Generic file name”, the variable max will be stored in the file Cameroun2000_max.img and
the minimum in Cameroun2000_min.img
Sampling period:
That is the time interval in days between two maps.
Offset:
As we consider that each image corresponds to one measure from the time-series, this offset
determines the day within the time interval assigned to an image. For example, with an offset
of 5, and a sampling period of 10, the 3th image corresponds to the day 25 (10 * 2 +5). The
minimum offset value is 1 and the maximum is equal to the sampling period.
Search complete season's between days:
In order to limit the location of the peak, you must specify here the range date where the
program should process the detection. The first value must precede the expected date of the
growth start, and the first value must exceed the dead of the season.
9
BAgS – User’s Manual - 2004
10
Number of days to estimate the lower value:
The lower season’s value is estimated from a time interval preceding the onset. You must
specify the number of days for this interval.
Minimum delta amplitude:
That is the minimum amplitude between the onset amplitude and the maximum amplitude.
Growth time:
In order to select correct vegetation growth cycle, you must specify here a minimum and a
maximum of time within the growth is realistic.
Threshold level at growth start:
Is the level on which we consider that the growth season starts.
Threshold level at end:
Is the level where we consider that the vegetation is dying.
Plateau cut-off (in % of delta amplitude):
In order to estimate the size of the plateau, we consider that while the difference between the
base line and the signal level is higher than a percentage of the delta amplitude, the vegetation
is at her high level. The threshold is computed as follow:
Threshold=(Max-Min)*cut-off/100+Min.
List of calculated map:
Each checked item in the list will produce a corresponding image as output. All others are
ignored.
- ProcBaseLine produces the lower level before the onset in the BaseLine image.
- ProcOnsetLevel produces the level at onset in the OnsetLevel image.
- ProcOnsetTime produces the date in days when the onset occurs in OnsetTime.
- ProcMaxLevel produces the level when this one reaches the maximum in MaxLevel.
- ProcMaxTime gives the date in days where the level reaches the maximum in MaxTime.
- ProcPlateauLevel gives the level of the plateau in the PlateauLevel image.
BAgS – User’s Manual - 2004
11
- ProcPlateauStartTime gives the beginning date of the plateau in PlateauStartTime.
- ProcPlateauEndTime gives the end date of the plateau in PlateauEndTime.
- ProcEndSeasonLevel gives the level when the season is dead in EndSeasonLevel.
- ProcEndSeasonTime gives the end date of the season in the EndSeasonTime image.
You can fix these parameters with the main window dialog, or write it yourself directly in a
text file. When you click on the “save” item of the file menu, BAgS create this file.
Entering the parameters manually in a text file:
You can manually modify the parameters file by editing it with a text editor.
Syntax is:
StringVariable [whitespace] = [whitespace] “value”
RealVariable [whitespace] = [whitespace] [sign] [digits] [.digits] [ {d | D | e | E}[sign]digits]
IntegerVariable [whitespace] = [whitespace] [{+ | –}] [digits]
BooleanVariable [whitespace] = [whitespace] [YES| NO|1|0|ON|OFF]
- The string must be quoted.
- A whitespace may consist of space or tab characters, which are ignored.
- Sign is either plus (+) or minus (–)
- Digits are one or more decimal digits. If no digits appear before the radix character, at least
one must appear after the radix character.
- The decimal digits can be followed by an exponent, which consists of the introductory letter
‘e’ or ‘E’ and an optionally signed integer (23e-2, or 5E4).
Here is an example:
GenericFileName
= "sen03"
ListFileName
= "E:\_FAO\Dec\Senegal\Sen03.lst"
WorkDir
= "E:\_FAO\Dec\Senegal\"
ImageDir
= "E:\_FAO\Dec\Senegal\map"
PlateauCutOff
= 20
BAgS – User’s Manual - 2004
SeasonBeginMin
= 91
SeasonEndMax
= 340
GrowthTimeMin
= 91
GrowthTimeMax
= 200
ThresholdBegin
= 0.12
ThresholdEnd
= 0.25
HumpampMin
= 0.1
SampleRate
= 10
DayOfImage
= 5
FirstDaysForLower= 30
ProcBaseLine
= 1
ProcOnsetLevel
= YES
ProcOnsetTime
= no
ProcMaxLevel
= 0
ProcMaxTime
= on
ProcPlateauLevel
= off
ProcPlateauStartTime= 1
ProcPlateauEndTime
= 1
ProcEndSeasonLevel
= 1
ProcEndSeasonTime
= 1
When you save your file, be careful to let it in a pure ASCII format.
12
BAgS – User’s Manual - 2004
13
User Interface
Overview:
From the Main window, you can fix parameters, and process all points. But also…
…edit the images list
…edit the the images list
…process the mean of all points
…select a point in the image
…and process it
BAgS – User’s Manual - 2004
14
Because BAgS has been designed to be called by other main application, such as
AgroMetShell, the user interface consists of a dialog type main window with a classic menu
bar that allow you to create, modify, test, and run your time-series IDA images.
This user interface uses standard Windows interface functionality along with a few additional
features to make the best adjustment of your parameters, and the treatment of your set of data,
easy to use.
The main window
The main window is a view of your parameter’s file. Each field of these reflect the exact
value of it. For any parameter that does not figure in the file, a default value is automatically
assigned. Refer to the section relative to the parameters for a complete description of the
different parameters and their range and default values.
The first field specify the file that contains the list of the IDA images. You can open and
manage this file by clicking on the “…” button at the right of the field, which open the “List
BAgS – User’s Manual - 2004
15
Editor”. You will see below, how to create or modify this list. You can specify, construct and
modify this list by clicking on the button at the right end of the field.
Clicking on the “…” button at the right of the “Image directory” or “Working directory”
fields allows you to select the good corresponding directory in a standard “Windows search
for directory” dialog.
The main menu:
File menu:
- Create a new “blank” parameters file by clicking on the “New” option. All numerical values
are set as default as explained in the “parameters and options” section of this paper.
- Open a parameters file by clicking on the “Open” option.
- Save the file by clicking on the “Save” or “Save as” option. BAgS will automatically
produce a text file as explained in the “parameters and options” section of this paper.
Run menu:
After you have set up your parameters and options, you can run the program for process the
whole map, or simply run it on a single point or on the mean of all points. This mean will be
treated like a single point.
Running a single point produce a graph like this:
This graphic window allows you to see the curves, print the graph, zoom it, or save the time
series vector to the disk by clicking on the mouse left button and on one of the options of the
context menu that appears.
Processing all points produces IDA maps results but no graph.
BAgS – User’s Manual - 2004
16
- Test your set up on a file by clicking on the “Test on file” option. This file must be a time
series vector previously created by BAgS or a compatible imported file. See information
about the format of a “time series vector” file.
- Test your set up on the mean of all points of the map by clicking on the “Test on mean”
option. BAgS will create a time series vector with the mean of all points from each map. After
processing of this vector, the results are displayed on a graph.
- Test your set up on a specific point of the map by clicking on the “Test on X,Y” option. This
will open a bitmap window of the first IDA map of the series. See the section “IDA map
viewer” for more details about the functionalities of this window. You can click on the map
for selecting the point you want to process and view the results on graphs.
- Process all points by clicking on the “Process all points” option. After all points have been
computerized, results that have been checked in the process list are stored in the
corresponding IDA map.
The IDA map viewer:
BAgS – User’s Manual - 2004
17
Opened by the “Test on X,Y” option of the “Run” main menu option, this bitmap type graphic
windows allows you to view the map, zoom it, print it, and select a specific point for process
it as a single point.
In the title bar, you can see the coordinates in pixel of this bitmap, followed by the
coordinates in pixel from the original IDA map, the coordinates of this point in Longitude and
Latitude, and at last, the value of this pixel pointed by the mouse cursor.
For selecting the point you want to process:
-
move the mouse cursor on the position at the good position,
-
click with right button of the mouse on this point,
-
click on the left button (the contextual menu should appears),
-
click on the “Process point” option,
that will start the computerization of the time series at this point.
The list editor:
BAgS – User’s Manual - 2004
18
This dialog box allows you to construct and manage lists of IDA images. It support “Drag and
drop” operation. You can thus select a file or a group of files outside the application and drag
it into the list. BAgS will automatically add the selected files in the list.
Add an image to the list:
Click on the Add button. A standard “file dialog” appears and let you select a file or a group
of files.
Delete an image from the list:
Click on the “Del” button or on the “Delete” option of the “Edit” menu.
Sort items in the list:
Click on the “Sort” button or on the “Sort” option of the “Edit” menu.
Add a missing image:
When some images of the time-series are missing, you must add these one as “missing” in the
list. Select the line just after the missing map. Click to the “Miss” button or on the “Add
Missing” option of the “Edit” menu to add a missing line before the selected line in the list.
Save the list:
Click on the “Save” or “Save as” option of the “File” menu.
Exit the list:
Click on the “Ok” button or on the “Quit” option of the “File” menu to reflect your action in
the “Image list” field of the main windows.
After the dialog is closed, the “Image list” field of the main windows is updated.
A cancel (or exit without save) action will restore this field in its original state when the “Ok”
action will update this field with the last opened list.
BAgS – User’s Manual - 2004
19
Using Bags Dll in your own application
Call of BAgS.dll from a C++ application:
At compilation time, BAgS.lib and BAgS.h must be present in your project directory.
You have just to add these two lines in your C++ source:
#include "BAgS.h"
...
BAgS() ;
...
At runtime, BAgS.dll must be in the usual location of any dll (in your executable directory or
in a well know path of the system such as C:\Windows, C:\Windows\System32, etc.).
Call of BAgS.dll from a Basic application:
Add these two line in your Basic application:
DECLARE FUNCTION RUNBAGS LIB "BAgS.dll" ALIAS "BAgS"()
SUB MYPROC
CALL RUNBAGS ()
ENDSUB
Put BAgS.dll in the usual location of any dll (in your executable directory or in a well know
path of the system such as C:\Windows, C:\Windows\System32, etc.) and run it.