Spatial Allocator is an Envision plug-in that allows for top-down allocation of variables onto the landscape. It allows one to define a variable to be allocated, along with allocation targets, generally expressed in area units, and constraints and preferences guiding where the variable can be allocated. Spatial Allocator tries to achieve the target allocation by testing IDU's to see if they satisfy any constraints definerd for the allocation, and then "ranking" the resulting IDUs based on preferences. A variable to be allocated is defined by an Allocation Set; multiple, competing pathways to acheive the allocation target are defined by one or more Allocations for that variable. At each Envision timestep, Envision will try to achieve the target defined for the Allocation Set by examining any Allocation within the Allocation set, weigh each Allocation for each IDU, and applying the most appropriate Allocation to the IDU. 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).


An example XML format input file for a SpatialAllocator is provided below. This input file defines a single Allocation Set for allocating fire on the landscape. The amount of fire to allocate is defined by the individual Allocations (alternatively, the target across all allocations can be defined at the Allocation Set level). The field in the IDU database to be set for this Allocation Set is the "DISTURB" column.

Two types of fire are being allocated: Low-severity, and Stand-replacing. Targets for both are defined within the Allocation. The 'expand' options indicate that once an IDU is selected for application of this Allocation, the area of application will "expand" to neighbors that meet the expand_query requirements, up to a maximum area defined by the expand_area attribute. Sites that are eligible for each Allocation are defined with the constraint query. Preferred sites are indicated with the preference tags.

<?xml version="1.0" encoding="utf-8"?>

<spatial_allocator area_col="AREA" method="score priority" shuffle_idus="1">

  <allocation_set name="Fire" col="DISTURB" use="1" >

     <allocation name="Low Severity Fire" id="21" target_source="timeseries" 
             expand_query="LULC_A=4 {Forest} or LULC_A=3 {Other Veg}" expand_area="3000000" >
        <constraint name="Forest Land" query="LULC_A=4 {Forest} or LULC_A=3 {Other Veg}" />        
        <preference name="global" query="LULC_A=3 {Other Veg}" weight="0.1" />

     <allocation name="Stand replacing Fire" id="23" target_source="timeseries" target_values="(1990,7000000),(2050,9000000)"
             expand_query="LULC_A=4 {Forest} or LULC_A=3 {Other Veg}" expand_area="3000000" >
        <constraint name="Forest Land" query="LULC_A=4 {Forest}" />
        <preference name="global" query="LULC_A=4 {Forest}" weight="0.1" />


Specific tags and attributes for define Allocations are described below.