[an error occurred while processing this directive]


GIS Control

Spatial data is cool and looks pretty too! This is the GIS Control Panel. Import your GIS data into your model, tell it how to resample the data and even rescale it. Check that you're happy with every aspect of how the model is going to intepret your spatial data. Plenty of security features here too to make sure that your data is valid plus a method to translate your binary data into ascii grids for faster import times into the model.

Spatial data in the model

Initially your model is populated (at object instantiation and variable initialization) with default GIS data, e.g., topography from a set of landscape templates and stochastic plant distributions. These default data sets for your spatial parameters are then overwritten by your spatial GIS data.

The sequence of events during an update of your model (also carried out prior to a simulation) is

The modeling software interprets (processes) your original GIS layers according to a set of rules / actions. This resampling algorithm is required to convert from the high resolution binary data (many thousands of pixels) to the grain of your model (typically a few hundred cells)
all of which can be done, and the results viewed, in the GIS Control. There is an additional trick to improve simulation times by converting everything to ascii grids, but more about that later.

Spatial data structure

When describig the spatial data structure of the modelling software, or indeed any data structure of any software, it is difficult to avoid delving too deeply into the software architecture that should otherwise be confined to the Internal Documentation. It should suffice to point out that this spatial version of the modelling software was born out of the previous nonspatial version (which can still be used by turning off the spatial processes in the Spatial parameter category).

Because of this development history the spatial data structure within each module (one for Climate, one for Soil, and one for each Plant and Animal component, e.g., annual_grass_1, herbivore_1, etc.) consists of distinct grids of nonspatial objects, i.e., spatial grids are amalgamations of individual cells with no inherent spatial elements. Plus it was thought that this was a prudent method to represent the "real" spatial world.

As an aside, and just so you know of an alternative that was considered, the software engineering antithesis of this would be to construct just the single grid across which would be spread the spatial properties for all modules (soil depth, topography, plant height, standing plant biomass, etc.). It really all boils down to a question of packaging; data is either stored within cells within objects (packages of associated data), or within objects within cells.
and as mentioned above, this is not the right place in this guide to give full justification of the decision not to go this route, so briefly, the programming solution to implement this data structure would be unwieldy by contravening the modelling software's object-oriented design principles, particularly encapsulation of 'like' data within objects.

So, we have a grid within each module with a spatial element or elements, the spatial variables. Your GIS data is required to give meaningful parameter values to these variables and you use the GIS Control to associate your GIS data layer files with them.

Spatial data in the modules

Details about spatial parameters in your model can be found in the Parameters section in this guide, but here is a quick description of the spatial elements that you can parameterize with your GIS data,
  • Site - Area Mask : a layer to define the extent of your site if less than the entire grid. Interpreted as zero and not-zero to give binary flags 0 and 1.
    The mask layer deals with any inconsistancies from having partial data for cells outside the site area, and also makes the model run faster as it omits the excluded cells (yellow) from the simulation process. Any combinations of cells are valid, i.e., your site doesn't need to be a solid shape as the one shown (red), but instead you could have a discontinuous shape with 'islands'. Also accessed through the Site Area Mask window.
  • Landscape - Topography : ideally in metres above sea level, but whatever defines differential redistribution of surface water by runoff following rainfall events. Default templates are available if real data is not preferred, e.g., because you need to check your data against a more controlled landscape form. These may be accessed through the Surface Topography window.
  • Climate - Rainfall : not really for small areas, but larger regions may experience spatial rainfall patterns.
  • Climate - Wind Speed : usually rare to find sufficient data to show spatial variation, but used in the plant growth processes.
  • Soil - Soil Fertility : important variable combined with runoff in dictating spatial patterns of plant growth. Index 1,2,3,4,5.
  • Soil - Soil Depth : assumptions underlying the vertical distributions of roots make this not such an important variable, but it is commonly available with other soil parameters.
  • Soil - Soil Type : A weighted score to estimate mixtures of soil components (e.g. clay=1.5, loam=3.5, sand=7.5). It may help to think of soil texture.

    and for each Plant type
  • Plant Initial Biomass : starting distribution of above ground biomass, but see detailed description for more information.
  • Minimum Height : standing height of lowest available forage. Zero for ground based vegetation, but useful for vertical partitioning of forage resources.
  • Maximum Height : standing height of highest available forage.

    and for each Animal type
  • Watering Points/Bomas : Herding practises tend to kraal livestock each evening which equates boma enclosures with daily returns to drinking water sources. Therefore, for now, Bomas are simply assumed in the same category as Water, i.e., a focal point to return to. In future, Water and Boma distributions may be separately defined if there is a case for sufficient temporal and spatial differences between their utilization. This may require input from a study of herding practises. Currently, the model simply returns the animal population / herd to the specified source at the end of each foraging day if directed by your options for water dependency and wet season herding accessed through the Parameter View window. Water/Boma location can also be set through the Water Locator window.
  • Foraging Range : herding practises and known barriers to animal habitat use and migration, e.g., habitat fragmentation by fencing, can be represented using a mask to denote where animals can and cannot go. Interpreted as zero and not-zero to give binary flags 0 and 1 as for your Site Area Mask.
Frequent/seasonal changes in rainfall distribution, wind speed distribution, herding practise or seasonal disruptions to animal habitat use will require a sequence of GIS layers to show these spatiotemporal changes. A mechanism to automatically load such a sequence of GIS data files is in development and is included on the wish list.

Spatial data format

The GIS file formats that you can currently use to import GIS data into the modelling software are IDRISI Raster binary (.img and .rst raster binary GIS layers which must be in the same folder/directory as their accompanying .doc and .rdc document files, respectively) and flat-file ascii grids. Vector files may be opened for viewing in the GIS Control but they are not currently supported for interpretation by the modelling software. ESRI shapefile compatability is on the wish list.

Spatial data input

The whole reason for the GIS Control is to make it easy for you to import your GIS data into your model and check that it is being dealt with (interpreted) correctly, meanwhile making any modifications necessary (manipulation).

The GIS Control window is essentially split into an upper half and a lower half. You can resize these panels by dragging the red splitter bar.
The upper panel houses everything that you need to get your GIS data safely into your model. Each of the spatial variables are listed by the module that they appear in, their parameter name, the file with which they are associated, your choice of resampling algorithm with which to interpret the original data, and the scaling rule which tells the model how you want to modify and use the original data in the model.

To associate a GIS data file with a parameter you enter a file path in the file column of the GIS Control. Click on the browse button and use the standard dialog box to navigate to your GIS file location.
Please note that the example GIS data is supplied as ascii flat-file grids to minimize file sizes but also also because this is a good way to speed up simulation times. More about this below.

To replace file path entries simply select the row, click the browse button and select another valid file. To delete an entry without replacing it with another file path, select the row and click the Clear Current button . To clear all entries click the Clear All button . Caution should be taken when near these buttons, there is no undo other than reopening your project and if that doesn't solve it because of a saving mishap then believe me it's a bugger having to find all your files again after a late night, bleary-eyed accident.

However, accident allowed for, when you have selected a valid GIS data file the file path is inserted into the GIS Control for that parameter and the GIS Control loads your GIS data file into the input data panel in the lower left of the window.

There are 2 optional levels of security that can be invoked with the security check boxes. The Exist Warning indicates when a file is specified but cannot be found. For example, sometimes files get renamed but the model entries are not changed accordingly. In this case the Exist Warning will show the file path in red. Valid file paths are otherwise shown in the default text colour, as are invalid file paths when the Exist Warning is switched off. Additionally the Exist Prompt shows a message box with the offending file path when you click on an invalid entry.
Once your IDRISI GIS file has been entered into the GIS Control, you can access it's associated document file by clicking the file information button to the left of the export toolbar.

Displaying your GIS data files in the input data panel is straight forward enough and relies heavily on the capacity of the excellent InovaGIS engine.

Spatial data engine

The blurb on the inovaGIS website runs

"The inovaGIS.org is a small community of people developing free software in Visual Basic, Delphi/Kylix and ASP for common, simple applications that use geographic information."

At least that is what it WAS. Truth is that the website doesn't seem to have seen any activity since 2004, and is actually only copyrighted up until 2003. Also I have never received a reply to any emails that I have sent over the years to Pedro Pereira Gonçalves who is the principal developer. However, the online help and examples have typically provided the solutions that I have needed and so I have Pedro to thank enormously for making this software available, and I hope he is well despite his silence.

Spatial data display

There are several features in the GIS Control to control the way that your GIS data is displayed. These controls can be seen to the left of the data input panel, and here.

Please see below to read about the display of interpreted data.

When your GIS data file is successfully displayed in the input data panel the file name and file path are shown at the foot of the panel. The first thing you may notice is that passing your mouse over your GIS data in the input data panel brings up a coordinate system of geocoordinates in square brackets at the top of the panel. The other number after the coordinates is the value of the pixel at that location. You can switch between georeferencing and pixel coordinates using the Co-ordinate System control.

GIS data files can be scaled to fit the display using the Zoom control which ranges from 0.125 to 8 times magnification.

Experience with GIS data comprising small numbers compared to thousands of metres above sea level has shown that inovaGIS needs a little help in displaying these weaker signal files. Hence the Signal Boost amplifies your input data (actually using an internal scalar that does not effect your data values) so that it becomes visible (detectable by inovaGIS).

The lower half of the display controls is dominated by the palette selection that can be used to view IDRISI raster files. It is included here to make it easier for you to work with your GIS data by allowing you access to familiar colour schemes that are optimal for displaying your GIS data files.

Spatial data interpretation

If, thanks to Pedro, displaying your GIS data is easy then processing your GIS inputs is another thing altogether. Processing your GIS data involves resampling the original data layers using the specified resampling algorithm. A resampling algorithm is required to convert from the high resolution binary data (thousands of pixels) to the grain of your model (hundreds of cells).

This is achieved by allocating membership of the many cells in your GIS data grids (where pixel number = cell number) to your model grids (where columns x rows = cells). Consider it like superimposing your model grids on top of your GIS data grids.
Once the allocation of pixels into model grid cells has been established the next stage in the processing scans all of the pixels within a model grid cell and constructs a summary statistic (descriptor) for the set of pixels, ignoring pixels holding the Missing data flag value if it has been set in your Preferences.

The various statistical measures available are,
  • Mean : simple average value of the set of pixels.
  • Adjusted mean : average value of the set of pixels which are scaled prior to summation so that the resulting global average for the entire model grid is equal to the global average for the GIS data. This is especially necessary when you want to use GIS data layers which are at differing scales, or your Site Area Mask does not accord with the extent of your other spatial data. Another example would be where you have constructed your spatial data from mismatched estimates, e.g., estimates of local plant biomass extrapolated from an plant indicator variable such as canopy cover, made using a value of plant biomass obtained from a larger sample area. The data sources are mismatched. In each case you may wish to resample your GIS data using the Mean resampling algorithm, but this would result in biased values for your model grids. The solution is to note the GIS data mean, carry out the resampling and then scale the resulting grid with artificial mean back to give the original mean value.
  • Sum : total of the pixel values.
  • Minimum : minimum value in the set of pixels.
  • Maximum : maximum value in the set of pixels.
  • Equal : the model grid cell ends up being assigned the nearest GIS pixel value where GIS and model resolutions are similar, or more commonly, the value of the last pixel resampled. This is less useful for continuous distributions of say plant biomass. Where it comes into it's own is for nominal data sets where the model cell value is known, e.g., soil fertility indices, or for prepared ascii input data as discussed below.
  • Binary : 0 for no data and 1 for non-zero data. Most useful for defining zones, e.g., animal foraging range and watering points.

Spatial data manipulation

The model grids cells values are now ready to be written to the spatial variables that you associated with your GIS data files. Overwriting the spatial variables is moderated by your setting for Scaling, as follows,
  • None: direct substitution of the initial spatial variable value with model grid cell value.
  • Use as scalar: spatial variable value is the product of itself and the model grid cell value.
  • Normalize and use as scalar: the model grid cell values are first scaled to fit within the range 0 to 1, before being multiplied with the initial value of the spatial variable.
  • Invert: the model cell values are subtracted from the maximum cell value for the entire model grid, and this difference is written to the spatial variable. Especially useful with binary data.
All this processing for resampling and scaling is only carried out prior to updating your model or running a simulation unless the Preview Grid Capture option is selected. To just use the GIS Control to assemble and display your GIS data files, unselect this option.

To see how your GIS data will be interpreted according to your selected resampling and scaling rules also within the constraints of your Site Area Mask switch on the Apply Mask in Preview tickbox which is active only after you have identified a valid Site Area Mask file. Your Site Area Mask will be displayed employing the colour set in your Preferences.

If it will help to see the model grid displayed also switch on the Show Grid Lines option. The Scale Grid Lines option becomes active when you zoom in from the original resolution (factors greater than 1). To show either the coordinate system for the model grids or the actual values within the model grids cells, use the Show Labels and Values/Co-ordinates options.

It may be useful to you to record the appearance of the interpreted data panel. To capture a bitmap image click on the camera button in the export toolbar.

Spatial data optimization

As you can see there is quite a lot of manipulation of your data that you can carry out in the GIS Control, even though it has limited GIS abilities. An advantage is to definitely work with ascii flat-file grids of your model grids. This gives great flexibility in editing your grids, either by applying the GIS Control to work with the same GIS data, resampling and scaling to get the desired distribution, or even by hand in a text editor or spreadsheet. This may sound archaic, but once your GIS data has been interpreted by the model, there is no longer an advantage of high definition data. The spatial data grain is now determined by your choice of model grain (size of model grids).

It is therefore important to not underestimate the size of your model grids early on otherwise you will end up with ascii grid files that are for smaller grids than the ones that you want to use, and/or having to redo some preparatory work in generating those ascii files.

An additional benefit of ascii flat-file grids simply that parsing a text file of limited size (model grids size) is a lot quicker than churning through binary raster files every time the data needs to be resampled. The modelling software is busy enough without being given this extra burden. Another becomes immediately apparent when you are trying to distribute your model and its associated data. This is why each of the example projects fits easily within a megabyte.

So, now that you are persuaded to convert your binary data into ascii, how do you do it? The answer is "easily", or "very easily".

The are 2 buttons provided on the Export toolbar for the purpose but first a word of caution. These are powerful tools in that they follow your directions to write and overwrite data files. This will work for any valid GIS data file entry in the GIS Control. Select each file you want to export as ascii. In fact it is of course the interpreted model grid version of your GIS data that you are actually going to export. Click on the Export Single Model Version button on the Export toolbar. You will be prompted for a destination for the exported ascii file. Use the standard dialogue to specify a location.
It might be a good idea to keep your exports separate from your original data. If you want to export all files to one folder you can set this in your Preferences.

Now, this is the clever bit, if you have asked for it in your Preferences, your exported ascii file will be inserted into the GIS Control in place of your original GIS data file. Please remember to reselect your Sampling Algorithm and Scaling as these will not be automatically reset, but this is on the wish list. As the input ascii file grid is now the same size as the model grids, it is appropriate to select "Equal" and "None", respectively.

The cleverer bit that makes this process "very easy" is the other button on the Export toolbar to Export All Model Versions which will move stepwise through all of your GIS Control data file entries and apply the Export Model Version procedure to each. With the correct combination of preferences it's possible to automatically convert your whole binary GIS data set for your project into the corresponding ascii flat-file grid format while you go and make a nice cup of tea.