dst.update

DESCRIPTION

This program is used to manage user-supplied hypotheses and evidences in a Dempster-Shafer knowledge base file. The knowledge base file is an XML format ASCII file which resides in its own 'DST' element inside the user's current mapset. Such a file is necessary to perform Dempster-Shafer Theory (DST) calculations using dst.combine . Although the knowledge base file can theoretically be edited with any ASCII editor, it is highly recommended to always use dst.update to make any changes to it. This ensures that the mathematical structure of the model layout will always remain intact.

If you do not know what DST is or why you would need this program, please refer to the dst.combine command's manpage for an introduction.

The dst.update command allows the user to register hypotheses in a knowledge base file and attach evidences which support these hypotheses. To get an overview of the DST model structure at any time, use the dst.view command. Knowledge base files themselves can be listed, created, deleted and renamed using a specialised set of commands.

Registering Hypotheses

As described in the dst.combine command's manpage, the user-suppplied hypotheses (type 'USER') form the backbone of any DST analysis. The Frame of Reference (FOD) is the set of hypotheses that cover all possible outcomes of the analysis. In the DST, this also includes two types of hypotheses, which the user does not have to supply.

The NULL hypotheses, which always exists.
Sets of all possible combinations of user-supplied singleton hypotheses, which exist if more than one hypothesis is supplied.

It is vital that the FOD is always complete and that the hypotheses are stored in the correct hierachical order. E.g., if three hypotheses {a},{b} and {c} were supplied, one after another, the correct and complete FOD would look like:

{NULL}
{a}
{b}
{a,b}
{c}
{a,c}
{b,c}
{a,b,c}

The order in which {a},{b} and {c} are given has no influence on the correctness of the DST calculations. Nevertheless, keeping the correct structure intact can be challenging if the FOD is subject to changes. With dst.update, the user can add, rename and remove hypotheses in the FOD, without having to worry about its structure. In fact, the user only adds, renames are removes singleton hypotheses (except {NULL}) , sets are always managed automatically and stored as type 'AUTO' in the knowledge base file.

According to the laws of combinatorics, the number of hypotheses sets in the FOD grows rapidly if more hypotheses are supplied by the user. Currently, up two 12 user-supplied hypotheses are supported, but it seems unlikely that DST calculations with more than 4-6 user hypotheses will finish within reasonable time, as processing time also grows exponentially.

You can manage user-supplied hypotheses by using the add=[hyp], del=[hyp], ren=[hyp] (plus new=[hyp]) parameters. All other hypotheses will automatically be updated in the correct way. Note that names of hypotheses, like filenames, must not contain spaces or special characters. They will also be treated case-sensitive so 'HYP' is a different hypothesis than 'Hyp'.

Attaching Evidences

Once all hypotheses have been specified (it is vital for correct results that no possible hypothesis be left out!), it is up to the user to specify which evidences support a given hypothesis (or set of hypotheses). Any evidence must be the result of a correct BPA calculation (see r.dst.bpa for more details on this).

Different GRASS map formats can be attached using the const=[name], rast=[name}, vect=[name] and site=[name] parameters. However, currently only GRASS raster maps or constant values can be used to supply evidence. Handling of other vector evidence is not yet implemented in the DST combination routines themselves. Thus, only evidence attached using the rast=[name] parameter will produce output if you call the dst.combine command. Evidence of type 'const' consists of a single floating point number. It can be useful for testing purposes and to get a feeling for what the DST functions do with your data.

If you need to remove erraneous or outdated evidence from a knowledge base file, you can use the clean=[hypothesis] and prune=[evidence] parameters (see description of parameters below).

If all hypotheses and evidences are present in the data base, they have to be grouped to define sources of evidence. This can be done using the dst.source command.

Parameters

file=name: Name of DST knowledge base file to modify. You can get a listing of DST knowledge base files in your current mapset by using dst.list .
add=name: Adds a hypothesis 'name' to the knowledge base. Naming conventions follow the same rules as filenames.
del=name: Deletes hypothesis 'name' (and all references in hypotheses sets) from the knowledge base file.
ren=name: Renames hypothesis 'name' (and all references in hypotheses sets) from the knowledge base file. New name must be specified using the new=[name] parameter (see below).
new=name: Specifies a new name for renaming a hypothesis.
const=value: Attaches a constant value as evidence to a hypothesis. As with all evidences, the target hypothesis must be specified using the hypothesis=[name] parameter.
rast=name: Attaches a GRASS raster map as evidence to a hypothesis.
vect=name: Attaches a GRASS vector map as evidence to a hypothesis (useless for now).
clean=name: Removes all attached evidence from a hypothesis (specified using hypothesis=[name]).
prune=name: Removes all references to an evidence from one or all hypotheses. The type(s) of evidence to detach can be specified using type=[name].
hypothesis=name: Specifies hypothesis to operate on. Note that order matters when refering to hypotheses sets: 'a,c' may exist, but 'c,a' not!
type=name: Type of evidence to detach (use in conjunction with prune=[hyp]). Possible options are const,rast,vect,*.
precision=value: Number of decimal places for storing evidence of type const. The default is '2'.

DESCRIPTION

Registering Hypotheses

Attaching Evidences

Parameters

USAGE

Notes

SEE ALSO

AUTHOR