Spatial Allocator

SpatialAllocator is an Envision plug-in that allows for "synchronizations" to be run whenever specified changes in the underlying spatial database (IDUs) happen as a result of some other Envision process running - in effect, a sync is a "listener" that responds when specific database changes occur. In that sense, it is similar to another Envision plug-in, Trigger. Defining a sync is straightforward - like most Envision plug-ins, SpatialAllocators are specified using an XML file, described below. SpatialAllocators are defined based on what field changes they are listening for. SpatialAllocators can be turned on and off for specific scenarios through use of the "use" attribute, which is exposed as a scenario variable (settable scenario by scenario in the study area project file.

PropertySpatialAllocatorTrigger
Is invoked based on: Detecting A specified value, a change of value, or range of values in a source columnEach IDU that satisfies a spatial query
Computation Time: Executes quicklyExecutes more slowly
Value used to update IDUs:a single value or range of valuesA Mathematical Expression, include field values


The basic XML format for a SpatialAllocator input file is provided below.

<?xml version="1.0" encoding="utf-8"?>
<syncs>
    <sync name='MySpatialAllocatorName' use='1' query='myQuery' >
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
            ...
        <outcome target_col="SomeCol" target_value='SomeOtherExpression" probability='SomeOtherProbability'>/>
    <sync>
    ...
    <sync name='MySpatialAllocatorName' use='1' query='myQuery' >
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
            ...
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
    <sync>
</syncs>

In the example above, for each time step, the sync "MySpatialAllocatorName" would invoked for every IDU for which the query "MyQuery" is satisfied. In that case, each outcome associated with this sync would be applied to the IDU database. Using the example above, the IDU field "SomeCol" would get populated with the result of evaluating the expression "SomeExpression"; the likelihood of that expression being applied is determined by the value "SomeProbability". Specific tags and attributes shown in the figure above are described below.


<sync> tag

The <sync> tag defines the name of the sync, the spatial domain of the sync, and whether the sync is enabled by default. Any number of <sync>s can be placed in the file; each operate independently of the other. SpatialAllocators are executed in the order specified in the input file; changes made by a 'higher' sync are not seen by "lower" syncs (the results of the sync outcomes aren't written to the IDU database until all syncs have executed.

<sync_map> tag

The <sync_map> tag defines the name of the sync, source and target columns, and the spatial domain of the sync, and whether the sync is enabled by default. Any number of <sync>s can be placed in the file; each operate independently of the other. SpatialAllocators are executed in the order specified in the input file; changes made by a 'higher' sync are not seen by "lower" syncs (the results of the sync outcomes aren't written to the IDU database until all syncs have executed.

AttributeDescriptionDefault ValueRequired?
name Name of the model Yes
query A query used to determine which IDU's are syncedYes
use Flag indicating whether this sync should be active during a run.  It is expled as a scenario variable.1 (use is enabled)No
[top]

<outcome> tag

The <outcome> tag specifies the IDU field to be updated when the sync is invoked, along with an expression that is evaluated to determine what value is written to the IDU field. Optionally, a probability (0-1) can be defined that determines the likelihood of that outcome actually being wrtten to the IDU.

AttributeDescriptionDefault ValueRequired?
target_col IDU field that will be populated by this outcomeYes
target_value a map expression that is evaluated when this sync is invokedYes
probability decimal fraction (0-1) specifying the probability that this outcome will be applied.1.0No
[top]

Below is an example sync input file.
<?xml version="1.0" encoding="UTF-8"?>

<!-- SpatialAllocator specifies a set of mappings between variables in one column to 
     variables in another column. <sync method: "useDelta" (default) or "useMap" -->

<sync method="useMap">

    <!-- this map looks for disturbances and flips them to there negative values at the begining of a step -->
    <sync_map name="Disturb Flipper" target_col="DISTURB" source_col="DISTURB">
        <map source_value="21">
            <outcome probability="1.0" target_value="-21"/>
        </map>
        <map source_value="23-25">
            <outcome probability="1.0" target_value="-23"/>
        </map>
    </sync_map>

    <!-- this map looks for disturbances and sets the time since disturbance to 0 -->
    <sync_map target_col="TSD" source_col="DISTURB">
        <map source_value="*">
            <outcome probability="1.0" target_value="0"/>
        </map>
    </sync_map>
</sync>