openModeller request files

26.02.2012 13:36 · GIS · openmodeller, howto

In the post about openModeller command-line tools, I have mentioned request files several times. When using openModeller from the command line, we have to deal with these files very often, as they allow us to perform almost all necessary actions and go from the input data to the results.

So let’s take a closer look at these files.

General information

A request file is a plain text file containing key-value pairs separated by one or more line feeds. Request files are often used as input data for various openModeller console tools. For example, using the request file, om_console can: create a model; apply an existing model to a set of layers; or create a model and immediately apply it to a set of layers. The om_viewer and om_sampler also work with request files.

Although the request file does not have a strict structure, it can be logically divided into several sections:

definition of the occurrence points
definition of the source layers used to create the model
final model definition
model projection settings
definition of the target layers (to be used for model projection)
definition of the model projection results
algorithm parameters

Lines starting with # are comments and will be ignored. Blank lines are also ignored.

Depending on the task, a request file may contain all or only some of the above sections. Let’s have a closer look at each section.

Definition of the occurrence points

As the name suggests, these are parameters related in one way or another to species occurrence points. This section includes the following parameters:

WKT Coord System — coordinate reference system of occurrence points in WKT (Well-Known Text) format. If the points are in different coordinate reference systems, it is necessary to convert them into a common CRS
Occurrences source — the source of the occurrence points. The source can be an absolute or relative path to a text file; an absolute or relative path to an XML file; the address of the GBIF service; the address of the TAPIR service
Note
Keep in mind that om_console can only work with one datasource type at a time.
Occurrences group — a label used to select points from the source (most often the name of the species). By default, the last value found in the list of points is used
Spatially unique — an optional parameter that can be used to exclude points with the same coordinates. The default value is false.
Environmentally unique — an optional parameter that can be used to exclude points with the same environmental and/or climatic conditions. The default value is false.

All these parameters are only used to create a new model. Here is an example:

WKT Coord System = GEOGCS["WGS84", DATUM["WGS84", SPHEROID["WGS84", 6378137.0, 298.257223563]], PRIMEM["Greenwich", 0.0], UNIT["degree", 0.017453292519943295], AXIS["Longitude",EAST], AXIS["Latitude",NORTH]]
Occurrences source = /home/alex/data/gbif/physalis_peruviana.txt
Occurrences group = Physalis peruviana
Spatially unique = true
Environmentally unique = false

Definition of the source layers

This section describes the layers used to create the model.

Map — a raster layer with continuous values that is used to create the model. Multiple parameters are allowed. As a value, you can use an absolute or relative path to a GDAL-compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```
Categorical map — a raster layer with discrete values that is used to create the model. Multiple parameters are allowed. As a value, you can use an absolute or relative path to a GDAL-compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```
Mask — an optional raster mask layer defining the area of interest. All occurrences outside the mask layer are excluded from the analysis. If not set, the first layer specified by the Map parameter is used as the mask layer. The mask layer must support NODATA values, a point falling in locations with a value of 0 will not be excluded from the analysis. As a value, you can use an absolute or relative path to a GDAL compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```

Note

Layers specified by the Map and Categorical map parameters can also exclude points from analysis if these points fall in locations with a NODATA value.

Example:

Map = /data/cru_bioclim/meanDiurnal.asc
Map = /data/cru_bioclim/meanDiurnalOverCoolestM.asc
Map = /data/cru_bioclim/meanDiurnalOverWarmestM.asc
Map = /data/cru_bioclim/meanFrostDays.asc
Map = /data/cru_bioclim/meanPrecip.asc
Map = /data/cru_bioclim/meanPrecipOverCoolestQ.asc
Map = /data/cru_bioclim/meanPrecipOverDriestM.asc
Map = /data/cru_bioclim/meanPrecipOverDriestQ.asc
Map = /data/cru_bioclim/meanPrecipOverFrostFreeM.asc

Mask = /data/cru_bioclim/stdevMeanTemp.asc

Final model definition

One of the results of the analysis is a species distribution model that can be saved to disk in XML format (the so-called “generated model”). If the request file isn’t used to generate a model, all parameters of this group should be omitted.

Output model — absolute or relative path to a file where the generated model will be saved

Output model = /home/alex/models/my_model.xml

Projection settings

A model previously created with om_console or om_model can be used as an input model and applied to a set of layers. In this case, all parameters related to occurrence points and source layers are ignored.

Input model — absolute or relative path to the generated model file

Input model = /home/alex/models/test_model.xml

Definition of the target layers

This group of parameters is only needed if you are applying the generated model to a different set of layers.

Warning

It is important to remember that the number of layers, their order, and the values they represent should match the layers used to create the model. For example, if the model was created using three layers (temperature, precipitation, and soil pH), then the second set of layers should consist of three layers describing the same values (temperature, precipitation, and soil pH).

Output map — a raster layer with discrete values that is used to project(apply) the model. Multiple parameters are allowed. As a value, you can use an absolute or relative path to a GDAL-compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```
Output categorical map — a raster layer with discrete values that is used to project (apply) the model. Multiple parameters are allowed. As a value, you can use an absolute or relative path to a GDAL-compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```
Output mask — an optional raster mask layer defining the area of interest. All occurrences outside the mask layer are excluded from the analysis. If not set, the first layer specified by the Output map parameter is used as the mask layer. The mask layer must support NODATA values, a point falling in locations with a value of 0 will not be excluded from the analysis. As a value, you can use an absolute or relative path to a GDAL compatible raster or, if openModeller is built with TerraLib support, a reference to a TerraLib raster in the format
```
terralib>dbUsername>dbPassword@dbType>dbHost>dbName>dbPort>layerName>tableName>columnName
```

Note

Layers specified by the Output map and Output categorical map parameters can also exclude points from analysis if these points fall in locations with a NODATA value.

Example

Output map = /data/clim_2050/meanDiurnal.asc
Output map = /data/clim_2050/meanDiurnalOverCoolestM.asc
Output map = /data/clim_2050/meanDiurnalOverWarmestM.asc
Output map = /data/clim_2050/meanFrostDays.asc
Output map = /data/clim_2050/meanPrecip.asc
Output map = /data/clim_2050/meanPrecipOverCoolestQ.asc
Output map = /data/clim_2050/meanPrecipOverDriestM.asc
Output map = /data/clim_2050/meanPrecipOverDriestQ.asc
Output map = /data/clim_2050/meanPrecipOverFrostFreeM.asc

Output mask = /data/clim_2050/stdevMeanTemp.asc

Projection results

The result of the projection (application of the model) is a raster file showing the species distribution in a given area. The extent of this area will be equal to the combined extent of all layers defined as ‘Output map’ and the mask layer. The coordinate reference system of the output raster, as well as the pixel size, will be the same as that of the template raster. The Output format parameter defines the template raster.

Output file type — data format of the output raster. At the time of writing the post, the following types are supported:
- GreyTiff — GeoTiff, valid values 0…254, NODATA — 255
- GreyTiff100 — GeoTiff, valid values 0…100, NODATA — 127
- FloatingTiff — GeoTiff, floating point datatype with valid values in the range 0.0…1.0 and NODATA set to −1
- GreyBMP — BMP, valid values 0…255, NODATA — 255
- FloatingHFA — Erdas Imagine, floating point datatype with valid values in the range 0.0…1.0 and NODATA set to −1
- ByteHFA — Erdas Imagine, valid values 0…100, NODATA set to 101
- ByteASC — ARC/Info ASCII grid, valid values 0…100, NODATA set to 101
- FloatingASC — ARC/Info ASCII grid, floating point datatype with valid values in the range 0.0…1.0 and NODATA set to −9999
Output format — a template raster that defines the coordinate reference system and pixel size for the output raster
Output file — absolute or relative path to the output file

Output format = /data/clim_2050/stdevMeanTemp.asc
Output file type = ByteHFA
Output file = /data/output/acacia-2050.img

Algorithm parameters

If the parameters of this group are not set, om_console will enter interactive mode, display a list of all available algorithms, and ask you to select the desired one. The algorithm parameters are prompted in the same way. If the algorithm and its parameters are set in the request file, om_console will work in non-interactive mode and process the request file without user intervention.

Parameters from this group are only required when generating a model.

Algorithm — algorithm identifier. If not specified, openModeller will stop processing and prompt the user to enter the algorithm identifier. To get the list of available algorithms and their identifiers, use `om_algorithm’ tool
Parameter — settings of the algorithm defined by the Algorithm key. Multiple keys are allowed. Parameters are set using the parameter_id parameter_value format

If some or all of the parameters are not set, om_console will prompt the user for the value of the missing parameters.

Here is an example of an algorithm definition

Algorithm = CSMBS
Parameter = Randomisations 8
Parameter = StandardDeviations 2
Parameter = MinComponents 1
Parameter = VerboseDebugging 1

The complete request file will look like this:

# Occurrence points
WKT Coord System = GEOGCS["WGS84", DATUM["WGS84", SPHEROID["WGS84", 6378137.0, 298.257223563]], PRIMEM["Greenwich", 0.0], UNIT["degree", 0.017453292519943295], AXIS["Longitude",EAST], AXIS["Latitude",NORTH]]
Occurrences source = /home/alex/data/gbif/physalis_peruviana.txt
Occurrences group = Physalis peruviana
Spatially unique = true
Environmentally unique = false

# Input layers
Map = /data/cru_bioclim/meanDiurnal.asc
Map = /data/cru_bioclim/meanDiurnalOverCoolestM.asc
Map = /data/cru_bioclim/meanDiurnalOverWarmestM.asc
Map = /data/cru_bioclim/meanFrostDays.asc
Map = /data/cru_bioclim/meanPrecip.asc
Map = /data/cru_bioclim/meanPrecipOverCoolestQ.asc
Map = /data/cru_bioclim/meanPrecipOverDriestM.asc
Map = /data/cru_bioclim/meanPrecipOverDriestQ.asc
Map = /data/cru_bioclim/meanPrecipOverFrostFreeM.asc

Mask = /data/cru_bioclim/stdevMeanTemp.asc

# Generated model
Output model = /home/alex/models/my_model.xml

# Layers used for projecting (applying) model
Output map = /data/clim_2050/meanDiurnal.asc
Output map = /data/clim_2050/meanDiurnalOverCoolestM.asc
Output map = /data/clim_2050/meanDiurnalOverWarmestM.asc
Output map = /data/clim_2050/meanFrostDays.asc
Output map = /data/clim_2050/meanPrecip.asc
Output map = /data/clim_2050/meanPrecipOverCoolestQ.asc
Output map = /data/clim_2050/meanPrecipOverDriestM.asc
Output map = /data/clim_2050/meanPrecipOverDriestQ.asc
Output map = /data/clim_2050/meanPrecipOverFrostFreeM.asc

Output mask = /data/clim_2050/stdevMeanTemp.asc

# Projection result
Output format = /data/clim_2050/stdevMeanTemp.asc
Output file type = ByteHFA
Output file = /data/output/acacia-2050.img

# Algorithm to use
Algorithm = SVM
Parameter = SvmType 0
Parameter = KernelType 2
Parameter = Degree 3
Parameter = Gamma 0
Parameter = C 1
Parameter = Coef0 0
Parameter = Nu 0.5
Parameter = ProbabilisticOutput 0
Parameter = NumberOfPseudoAbsences 500

As you can see, there is nothing complicated about request files. A simple text format makes it easy to create them programmatically and then use them to process data.

⮜ Prev

Next ⮞