ENVISION

Target: Basic Idea

Target is a plugin that specifies a landscape variable whose total value across the landscape is represented as a trajectory, described as a rate or as a time series, and a set of "allocations" that describe a target distribution (capacity) surface in terms of underlying spatial attributes. It provides a "top-down" allocation mechanism where landscape targets are specified, and the Target model tries to allocate that variable onto the landscape in ways that achieve the target (if possible) by allocating the variable based on the target's allocation rules.

Target values of the allocated variable to be achieved at a landscape level are specified in the <target> tag using several forms described below. Spatially, allocations are based on "rules" that defined a capacity surface; based on these rules, Target allocates the variable across space in a way that move an existing density surface towards the capcity surface. By default, the allocation process distributes "new" values of the target variable proportionately to the difference between the existing density surface and the capacity surface; however, this can be biased by specifying preferences that in effect warp the capacity surface.

Note that if capacity queries (regions) overlap, the one specified FIRST has precedence over successive allocations.

Multiple allocation scenarios can be described for a given target by specifying multiple <allocation_set> blocks within a <target> block, each with a unique "id" (integer) and "name" attribute. These id's are exposed as scenario variables to the application.

Example Use Cases

Allocating new population growth on the landscape in response to zoning-defined capacities relative to existing population density patterns

Target Input File Format

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 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.

Tag Definitions for Target

This section defines high-level elements for a Target model. Attributes supported by this tag are defined below:

Attribute	Description	Default Value	Required?
name	Name of the model	Target	No
description	Description of the Target model		No
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. Intermediate times values are interpolated (linearly) between nearby specified points.		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]	AREA	No
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_params	Boolean flag (0/1, or T/F) indicating whether target should by run in parameter estimation mode. See below for details.		No

[top]

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:

Attribute	Description	Default Value	Required?
name	Name of the report		Yes
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:

Attribute	Description	Default Value	Required?
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:

Attribute	Description	Default Value	Required?
name	Name of the Allocation Set		Yes
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]

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:

Attribute	Description	Required?
name	Name of the Allocation Set	Yes
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]

An Example Target Input File

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>
</target_process>