Target

The Target plug-in module allocates one or more items to a landscape dynamically based on achieving global targets. In Target, the allocation process is based on the difference between a capacity surface and an existing density surface: The spatial pattern of allocation the target is driven by the difference between the current capacity and existing density for each IDU in the landscape, biased by optional "preference factors" that modify the capacity surface.

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

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

<target_process>
  <target name="First Target" method="rateLinear" value="SomeValus" col="MyCol"  capCol='MyCapCol' availCol='myAvailCol'
          pctAvailCol='MyPctAvailCol' >
<report id='1' name='Some Name' query='SomeQuery' /> ... <report id='2' name='Some Other Name' query='SomeOtherQuery' /> <const name="SomeConstant" value="2.3" /> ... <const name='SomeOtherConstant' value='6' /> <allocation_set id="0" name="My Scenario"> <capacity name="Some Capacity" query='SomeQuery' value="SomeEvaluationExpression" multiplier="1.0" /> ... <capacity name="Some Other Capacity" query='SomeOtherQuery' value="SomeOtherEvaluationExpression" multiplier="1.0" /> </allocation_set> ... <allocation_set id="1" name="Another Scenario"> <capacity name="Some Capacity" query='SomeQuery' value="SomeEvaluationExpression" multiplier="1.0" /> ... <capacity name="Some Other Capacity" query='SomeOtherQuery' value="SomeOtherEvaluationExpression" multiplier="1.0" /> </allocation_set> </target> ... <target name="Second Target" method="rateLinear" value="0.016" col="MyCol" capCol='MyCapCol' availCol='myAvailCol'
          pctAvailCol='MyPctAvailCol' > ... </target> </target_process>

In the example above, for each time step, the targets "First Target" and "Second Target" would be invoked for every IDU for which the target's query is satisfied. Target would determine an appropriate target to achieve at that time (based on the targets' method and value attributes) globally, and attempt to achieve that value by allocating the target value over the IDUs. The allocation process depends on the difference between the IDU's current value for the target attribute and the IDU's capacity, determined by the capacity expression for that particular allocation. Each IDU is updated, with the new target attribute value determined subject to the following constraints:

  • Achieving the global target value (summed over all IDUs)
  • Allocating the global target proportionally across the IDUs based on the IDU-level difference between the exising IDU-level target value and the IDU's capacity.

Specific tags and attributes shown in the figure above are described below.

<target>

This section defines high-level elements for a Target model. Attributes supported by this tag are defined below:
AttributeDescriptionDefault ValueRequired?
name Name of the modelTargetNo
description Description of the Target modelNo
method Method used to evaluate the target. One of:
  • rateLinear: value is interpreted as a constant growth rate (decimal percent (0-1) of initial value/year)
  • rateExp: value is interpreted as an exponential growth rate (decimal percent (0-1)/year)
  • timeseries_constant_rate: reserved for future use
  • timeseries: value is interpreted as pairs of values. See "value" below for details
Yes
value Value(s) used to compute targets. This is a 'per-unit-area' value. Format depends on the 'method' attribute above.
  • For rateLinear and rateExp, 'value' is a decimal percent, e.g. '0.1' indicates a 10 percent/year increase
  • For timeseries, 'value' is a set of (time,value) pairs, separated by semicolons, e.g. '(0,100);(10,200);(50,0)' indicates that the target value would start at 100 (time=0), ramp linearly to 200 by year 10, and then decline linearly to zero by year 50.
Yes
col IDU Field containing the target to be allocated, (per-area basis). [input]Yes
areaCol IDU Field containing the area, in map units, of the IDU [input]AREANo
densXareaCol IDU Field populated with the total quantity of the target (absolute quantity). If not specified, this information is not written to the IDU coverage. [output]No
capCol IDU Field populated with the total capacity of the IDU (absolute quantity). If not specified, this information is not written to the IDU coverage. [output] No
capDensCol IDU Field populated with the capacity of the IDU, on a per-area basis. If not specified, this information is not written to the IDU coverage. [output]No
availCol IDU Field populated with the available capacity of the IDU (absolute quantity). If not specified, this information is not written to the IDU coverage. [output]No
availDensCol IDU Field populated with the available capacity density of the IDU (per area basis). This is (capacity density - population density). If not specified, this information is not written to the IDU coverage. [output]No
pctAvailCol IDU Field populated with the decimal percent of capacity available (0-1). If not specified, this information is not written to the IDU coverage. [output]No
prefsCol IDU Field populated with the preference score for the IDU. If not specified, this information is not written to the IDU coverage. [output]No
query Map Query specifying the spatial domain in which the target model is run. If not provided, the model is run for the entrie IDU extents.No
estimate_paramsBoolean flag (0/1, or T/F) indicating whether target should by run in parameter estimation mode. See below for details.No
[top]

<report>

The <report> tag is nested with the <target> tag. Multiple report tags are supported. A target report reports the portion of the IDU area that satifies the specified query. Attributes supported by this tag are defined below:
AttributeDescriptionDefault ValueRequired?
name Name of the reportYes
query Map Query specifying which IDU's are to be included in the report.Yes
[top]

<const>

The <const> tag is nested with the <target> tag. Multiple const tags are supported. Each const provides a variable name and associated value that can be used in the 'value' expressions define for a 'capacity' definition. They are used to make the capacity expression more readable. Attributes supported by this tag are defined below:
AttributeDescriptionDefault ValueRequired?
name Name of the constant. This should not include blanks or non-alphabetic characters other than '_', and should start with a letter.Yes
value Number giving the value of this constant. Expressions are not supported.Yes
[top]

<allocation_set>

The <allocation_set> tag is nested with the <target> tag. It defines a particular Allocation Set. Multiple allocation_set tags are supported. Allocation Sets are are the heart of Target. An Allocation Set defines the capacity of each IDU for the field defined for the parent <target> tag, specified using <capacity> tags nested within the parent <allocation_set> tag. If you are using multiple scenarios, each of which uses different target definitions, you typically will define an allocation_set for each scenario. Attributes supported by this tag are defined below:
AttributeDescriptionDefault ValueRequired?
name Name of the Allocation SetYes
id Unique identifier for this Allocation Set. This is exposed as a scenario variable, allowing you to enable or disable the Allocation Set for a specific scenario.Yes
[top]

<capacity>

The <capacity> tag is nested with the <allocation_set> tag. It defines, at the individual IDU level, the 'capacity' of the IDU for the target field. Capacities are defined for specific collections of IDU's be specifying a query and a value expression. Any number of capacities can be defined by specifying distinct queries for each <capacity> definition. Attributes supported by this tag are defined below:
AttributeDescriptionDefault ValueRequired?
name Name of the Allocation SetYes
query Map Query specifying which IDU's the capacity expression applies to.Yes
value Map Expression defining the value of the capacity of each IDU satisfying the query.Yes
[top]

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

<target_process>
<target name="Population" method="rateLinear" value="0.016" col="POPDENS"  capCol='POP_CAP' availCol='POP_AVAIL' pctAvailCol='P_POP_AVAI' >

  <report id='1' name='Portion of Growth Added Within UGB' query='UGB > 0' />
  <report id='2' name='Portion of Growth Added Outside UGB' query='UGB = 0' />
  <const name="peoplePerDU" value="2.3" />

  <!-- the following are in DU/acre -->
  <const name="densUrban" value="20" />
  <const name="densResHigh" value="18" />
  <const name="densResMed" value="12" />
  <const name="densResLow" value="6" />
  <const name="densRR" value="0.1" />
  <const name="densResort" value="0.1" />
  <const name="densRC" value="0.005" />
  <const name='densAg' value='0.025' />
  <const name='densFor' value='0.020' />
  <const name='densMixed' value='6' />

  <allocation_set id="0" name="Base Scenario">
    <capacity name="ResHigh"       query='zone=20'                        value="densResHigh*peoplePerDU/4047"  />
    <capacity name="ResMed"        query='zone=21'                        value="densResMed*peoplePerDU/4047"   />
    <capacity name="ResLow"        query='zone=22 or zone=23 or zone=27'  value="densResLow*peoplePerDU/4047"   />
    <capacity name="RuralRes"      query='zone=26 or zone=50'             value="densRR*peoplePerDU/4047"       />
    <capacity name="Resort"        query='zone=40'                        value="densResort*peoplePerDU/4047"   />
    <capacity name="RuralComm"     query='zone=29'                        value="densRC*peoplePerDU/4047"       />
    <capacity name="Forestry"      query='zone=14 or Zone=15'             value="densFor*peoplePerDU/4047"      />
    <capacity name="MixedUse"      query='zone=10 or Zone=11'             value="densMixed*peoplePerDU/4047"    />
    <capacity name="Agriculture"   query='zone=16 or Zone=17'             value="densAg*peoplePerDU/4047"       />
  </allocation_set>

</target>