Policies in ENVISION represent the fundamental unit of decision-making – they define and constrain the range of possible
decisions an actor can make, and define the outcomes resulting from an actor selecting and applying the policy to an IDU.
Policies can be thought of as “strategies” or “decision rules” available to actors.
Policies in Envision are computational entities that are used by Actors to make adoption choices about
landscape management strategies that are available to them. Policies can be very simple or quite complex, depending on the
needs of a particualr application.
In general, policies primarily define three things:
- The goals or intentions behind the policy, defined in terms of Envision metagoals. If no metagoals are defined, then no
goal information needs to be provided for a policy.
-
The site attributes, expressed as a spatial query on the IDUs, that define where in the landscape th policy is operative (i.e.available
to Actors as a possible strategy).
-
The Outcome, or Outcomes, that occur on the landscape if an Actor chooses to adopt the policy.
Policies definitions must be supportable by
the underlying landscape attributes contained in the IDU coverage; for example, if a policy is to be constrained to only apply in
riparian areas, then the IDU coverage must have a representation of what defines a riparian area. Similarly, if a policy outcome is to
change a site from undeveloped to developed, then the IDU coverage must have an attribute or attributes consistent with that representation.
ENVISION can contain any number of policies. Users can define new policies, or edit/delete existing policies, using the Policy Editor.
The Policy Editor is available from the Edit Policies option on most ot the main ribbon tabs.
Policies are stored as XML in either the project (.ENVX) file or as a separate XML document, as indicated in the <policies>section of the project file.
Policies in ENVISION have a number of attributes that can be specified by a user or application developer through the Policy Editor in Envision, or be directly modifying
the XML document used to hold policy definitions. The Policy Editor presents these attributes on a series of tabs in a dialog box. The attributes, organized by tab, are described below.
Similarly, an example policy XML file is shown below.
Basic Properties Tab: This tab, shown to the right, allows specification of some basic policy attributes as described in the following table.
Additionally, it allows the creation of new policies, cloning of existing policies for modification, deletion of policies, and the
selection of the color used to represent the policy application in thematic maps and plots.
| Policy Attribute | Description |
|---|
| Effectiveness Period | How long (in years) this policy remains in effect after an actor selects it, expressed as a range between some minimum and maximum number of years. This is useful if you want to specify a temporal “footprint” for a policy. It is particularly useful in combination with the “Exclusive” attribute describe below. To utilize this attribute, check the “The effectiveness of this policy persists for a period after application” checkbox and specify the minimum and maximum persistence periods. The actual effectiveness period of a given policy application is selected stochastically from a uniform distribution between the minimum and maximum specified. |
| Is Mandatory | Specifies whether this policy is mandatory. Mandatory policies are always applied by actors on IDU’s where the site attributes are satisfied |
| Start Date | Specifies, if checked, that the policy does not become available to actors until the specified number of years have passed from the beginning of the analysis period. |
| End Date | Specifies, if checked, that the policy is no longer available to actors after the specified number of years have passed from the beginning of the analysis period. |
| Is Scheduled Policy | Indicates, if checked, that the policy occurs automatically (independent of an actor decision) at the specified point in time (specified as the start date, the number of years since the beginning of the analysis period) |
| Is Exclusive | Indicates that this policy, when selected by an actor and applied to an IDU, prevents any other policies from being applied to the IDU until the policy expires, as indicated by its effective period. |
| Shared Policy | Part of the editing control system for policies. If checked, the policy is available to any user of the policy database specified in the Project file; otherwise, only the author of the policy can use it in an analysis. |
| Editable Policy | Part of the editing control system for policies. If checked, the policy can only be edited by the author of the policy; otherwise, any user of the policy database specified in the Project file can edit/modify the policy. |
| Narrative | Textual description of the policy. This can be used to document the policy or provide other information about the policy |
Site Attributes Tab: This tab, shown below, allows the construction of spatial queries that specify where in the landscape the policy may be applied.
ENVISION has a built-in query language that is used in the Site Attribute Specification. The query allows a range of logical and spatial operators,
and is described more fully in Appendix 3. If ENVISION’s “Map” tab is active, the [Update Map] button will execute the current Site Attribute Query
and show where on the map the Policy is potentially applicable; this is a very useful feature for determining whether the Site Attribute Query is
meeting your requirements for the policy.
To specify a Site Attribute Query, the Policy Editor provides a query builder. Queries can be types directly into the Site Attribute Query field
of the Policy Editor, or can be constructed using the builder functions provided. Field/Value attributes are constructed by selecting the
desired Field/Operator/Value sets and pushing the “Add” button, which insert the specified triplet at the current insertion point in the query string.
Similarly, a spatial operator can be inserted into the Site Attribute Query by selecting the [Spatial Operators] button, which brings up
the Spatial Operators dialog box. The arguments to the spatial operators include a query string that defines the target of the
spatial operator, using syntax consistent with any other ENVISION spatial query.
Globally Constraining Policy Adoption
Globally, policy application with a given time step or throughout a simulation can be constrained in various ways. The constraints are defined
using the <global_constraints> tag, which is a child of the <policies>> tag - these define globally the type and value of the constraint.
Additionally, policy-level impacts on the global constraint are defined using <constraint> tags nested with the <policy> tag. These tags are defined below.
<global_constraints> (<policies> child tag)
| Attribute | Description | Default Value | Required? |
|---|
| name | Identifier associated with the constraint | | Yes |
| type | Type of constraint applied during a given timestep. One of:
'resource_limit' - constraints policy selection for constrained policies to a certain (maximum) level.
'max_area' - constrains policy selection to a certain (maximum) area.
'max_count' - constrains policy selection to a certain (maximum) number of applications. | | Yes |
| value | The value associated with constraint. Can be a number, an application variable, or an expression | | Yes |
<constraint> (<policy> child tag)
| Attribute | Description | Default Value | Required? |
|---|
| name | Identifier associated with the constraint | | Yes |
| gcName | Name of the associated global constraint (see above) | | Yes |
| basis | Basis for interpreting cost calculations. One of:
'unit_area' - costs are defined on a per-unit-area basis.
'absolute' - costs are defined on an absolute basis. | 'unit_area' | No |
| lookup | Costs are defined in a lookup table in a CSV file. lookup value is of the form:
'pathToCSVFile|lookupCol1=lookupValue1;{lookupCol2=lookupValue2,...}'.
At runtime, for each IDU, the cost is determined by "looking up" the IDU in the lookup table using the field columns defined in the lookup specification. For example:
lookup='Costs.csv|manage=14;vegclass=@vegclass;PrevTrt=@PrevTrt' indicates that cost information comes from the lookup file 'Costs.csv', and values are determined by looking at the row where the CSV field labeled [manage]=14, the CSV field [vegclass] is the [VEGCLASS] value from the IDU database, and the CSV field [PrevTrt] is the {PrevTrt] value from the IDU database. Initial Cost and Annual Maintenance Cost fields in the lookup CSV file are defined in the 'initCost' and 'maintenanceCost' attributes defined below. | not defined | No |
| initCost | The initial cost of adopting the policy. If not using a loookup table, this should be a number. If using a lookup table, the should be a column name in the CSV file used to look up the value. | | No |
| maintenanceCost | The annual maintenance cost of adopting the policy. If not using a loookup table, this should be a number. If using a lookup table, the should be a column name in the CSV file used to look up the value. | | No |
| duration | The period after policy adoption that the annual maintenance costs during which the maintenance costs are applied. (NOTE: Not currently used) | | No |