In this section, Envision's input files are described. These are essential to defining and configuring an Envision application. Envision consists of a number of files that collectively provide input to drive a futuring analysis. These are shown in the figure below and described here.

The Project File is an XML-based file that specifies a number of settings and inputs required for a given ENVISION application. It is organized as a series of sections, specified in a particular order. Each section is specified by a header of the form <section_name>. The Project File is a standard ASCII (text) file that can be edited with Notepad or any other ASCII editor, or any XML-based editor. Generally, this file is autogenerated by Envision and does not need to be edited directly. Instead, Envision provide a Project File Editor that allow maintenance of this file. However, some developers prefer to maintain this file by hand, providing more flexibility.

When starting a new project, Envision will prompt for the name and path for this file, and automatically create a basic Project file.

The sections of the Project file include the following:

Section Description
<settings> section defines high-level Envision settings
<layers> section defines map layers (coverages) to be used in the application
<zooms> section defines predefined viewing levels, locations
<app_vars> section defines any global application variables used by the model
<models> section defines any autonomous process models used in the application
<evaluators> section defines any evaluative models used in the application
<visualizers> section defines any non-standard visualizers used in the application
<metagoals> section defines dimensions of actor values/evaluative models/policy objectives space
<lulcTree> section defines land use/land cover hierarchy
<actors> section defines land use/land cover hierarchy
<policies> section defines land use/land cover hierarchy
<scenarios> section defines land use/land cover hierarchy

Individual sections of the Project file are described below.


<settings>

Attribute Name Definition Values Required?
Envision Environment
debug Reserved No
logMsgLevel Level of logging messages 0=log everything (default),
1=log critical events,
2= log nothing
No
noBuffering Determines where buffering is suported in policy outcome 0=buffering supported
1=buffering not supported (default)
No
parallel If enabled, allows evaluative models and autonomous processes to be run in parallel if multiple CPU cores are available 0 = disable parallel execution of plugins (default)
1 = enable parallel execution of plugins
No
path Adds the specified path(s) to the Envision PATH search; multiple paths must be separted by ';' or '|' No
deltaAllocationSize “Chunk” size, in bytes, by which new deltas are allocated Generally, this can be ignored. 0 (default) allocates delta arrays in 32KB chunks. No
Project Setup
spatialIndexDistance Minimum distance for a spatial index to use. 0 will disable loading of spatial index; positive values will check any existing spatial index to be sure it is sufficient, and rebuild it if necessary. Large values make take a long time to build the index. You should set this to whatever the maximum distance any of your spatial queries, Expand() functions, etc. might use. (Default=0) No
areaCutoff Minimum area of polygon for which a label, if defined, will be shown. Measured in map units. Used to control label display for smaller polygons. 0 indicates to display labels regardless of polygon size No
policyPrefenceWt default weight used for policy scoring preferences during actor decision-making 0 to 1 (the sum of actorAltruismWt, actorSelfInterestWt, and policyPrefenceWt should equal 1) No (defaults to 0.33)
addReturnsToBudget When considering cost limitations on policies, whether to include negative costs (returns) to the available budget. 0=don't add returns (default), 1=add returns No
mapUnits Map Units of the IDU coverage ‘feet’, ‘meters’,’degrees’,’unknown’ (default) No
Constraints Reserved No
Runtime Control
startYear Default starting year of runs. This can be changed at runtime. No (defaults to '0')
defaultPeriod Default length (in years) of runs. This can be changed at runtime. No (defaults to '25')
startRunNumber starting run number for this session, used to control autogenerated output file names. No (defaults to '0')
multiRunIterations Default number of runs used during multirun (Monte Carlo) simulations. THis can be changed at runtime. No (defaults to '20')
dynamicUpdate Indicates whether on-screen maps/views/text are updated during a run (slows performance) 0=no dynamic update
1=Update Views annually
2=Update Map annually
4=Update year of simulation on Map
8=Update which process is running on Map
16=reserved
No (defaults to '3')
discardMultirunDeltas Frees memory associated with delta arrays during successive monte-carlo runs during a multirun. Because delta arrays can have a large memory footprint, this may provent running out of memory during a multirun.
0=retain delta arrays during multiruns (default),
1=discard deltas during multiruns
No
Actor Setup
actorInitMethod Method used to initialize Actor weights 0 = no actors (default)
1 = actors are created from weights specified in the IDU coverage.
2 = actors are created from Groups defined in the project file. The IDU cover contains the group ID in a field called ACTOR
3 = actors are created based on a query string specified for the actorGroup in the project file
4 = a single actor is created from a single ActorGroup specified in the project file
5 = random actors are generated
No
actorAssociations Reserved for future use No
loadSharedPolicies Determines whether shared policies are loaded from the policy database 0=don’t load shared policies
1=load shared policies (default)
No
actorDecisionElements Indicates globally what elements of decision-making are available to actors. This is an integer that is the sum of the following:
1 – self-interested decision making
2 – altruistic decision making
4 – global policy preference
8 – utility
32 – social network influences
For example, if the application wants to allow 1,2 and 4, but not 8 and 32, then this flag should be set to (1+2+4)=7.
Note that 8 (utility) requires a user-defined autonomous process to populate a “UTILITY” field, and 32 (social network) requires that a social network be defined. See relevant topics for more information.
No
actorDecisionMethod Determines whether actors select policies proabilistically or always selecting the “best” policy 1=probabilistically select policies based on scores (default) 2= always pick policy with the highest score
dynamicActors Reserved for future use No
shuffleActorPolys If enabled, the polygon order by which actors make decisions is randomized at each step 0 = used fixed order (default)
1 = randomize order at each step (slightly more expensive computationally)
No
Output Control
collectPolicyData Flag indicating whether policy statistics are collected during a run. 0=don't collect, 1=collect (default) No
exportMapInterval Default map export interval (years) during a run -1 =do not export maps during a run (default)
Positive value = export IDU map at the specified interval during a run.
Note that this can be controlled interactively during run-time as well. Exported maps will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportBmpInterval Default map export (as BMP's) interval (years) during a run -1 =do not export maps during a run (default)
Positive value = export IDU map at the specified interval during a run. Exported BMP's will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportBmpPixelSize Cell size (in map units) for exporting bitmaps (.bmp). Only used if exportMapInterval > 0 Must be a positive value, in map units
exportBmpCols String indicating with column(s) of the IDU coverage should be exported. Ignored if BMP export is disabled. Comma-separated list of field names to be exported a bitmaps. If not specified and exporting bitmaps is enabled, the currently active field is exported. No
exportOutputs Enables automatic export of CSV files containing model results and exposed variables at the end of a run 0 = don’t export model outputs
1 = export model outputs
Exported files will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportDeltas Flag indicating whether to export the delta array at the end of the run 0=dont' export delta array (default)
1=export delta array
No
exportDeltaCols String indicating with column(s) of the delta array should be exported. Ignored if delta export is disabled. Comma-separated list of field names to be exported inthe delta array. If not specified and exporting delta arrays is enabled, all field will be included in the exported delta array No

 

<layers>

Coverages included in an Envision application are specified within the <layers> tag. Individual layers are defined with individual <layer> entries. The first <layer> entry is required to be the IDU coverage. Additional layers are dependent on the specific needs of the models used in the application.

Attributes for the <layers> tag are defined below.

Attribute Name Definition Values Required?
bkgr The path to a background image displayed "underneath" the coverages described below.. No (no background image is displayed)
left The "real world" x coordinate of the left hand side of the image (expressed in map units) Yes, if 'bkgr' is defined.
right The "real world" x coordinate of the right side of the image (expressed in map units) Yes, if 'bkgr' is defined.
top The "real world" y coordinate of the top side of the image (expressed in map units) Yes, if 'bkgr' is defined.
bottom The "real world" y coordinate of the bottom hand side of the image (expressed in map units) Yes, if 'bkgr' is defined.
prjFile The path to a projection file for the image. If not specified, the projection of the IDU coverage is assumed. No

Nested within the <layers> tag, individual coverages are specified with <layer> tags. Attributes for this tag are defined below.

Attribute Name Definition Values Required?
name A name associated with the coverage. Any string Yes
path The path to the coverage on disk Yes
initField Initial field to be displayed after the coverage is loaded into Envision Any valid field No (defaults to first field)
overlayFields No
color Color for drawing polygon/line edges, expressed as an RGB triplet, i.e. r,g,b Example: '0,0,0' results in a black polygon/line edge No, defaults to '140,140,140' (gray)
fieldInfoFile The path to the field information file (legend) for this layer. If not specified, a file matching the shape file but with an xml extension is assumed. No
labelField A field in the coverage containing string used for labeling features Any valid string field No (labels won't be drawn)
labelFont The name of the font used to draw labels No, defaults to 'Arial'
labelSize The size of the labels to be drawn No, defaults to '120'
labelColor Color for drawing labels, expressed as an RGB triplet, i.e. r,g,b Example: '0,0,0' results in a black font No, defaults to '255,255,255' (white)
labelQuery A spatial query used to determine which IDU's should be used for labeling An valid spatial query No, defaults to all IDUs
type The type of the coverage. -1=infer from extension (default),
0=shape file,
1=integer grid
2=floating point grid. For grids, this attribute must be set to either 1 or 2
No
records Number of coverage database records to load. Specifying -1 indicates to load all records. Only applies to shape files. No (defaults to -1)
expandLegend Flag indicating whether legend for the layer is initially expanded. 0=don't expand, 1=expand (default) No

<zooms>

This section allow defintion of predefined "zoom" extents. Similar to the other sections, the parent <zooms> tag can have zero or more <zoom> children tags. Each <zoom> tag defines a zoom extent and has the following attributes:

Attribute Name Definition Values Required?
name Name of the  zoom.  This appears in the "Zoom to" dialog box in the Envision interface string Yes
left x-coordinate of the left side of the view, in map layer coordinates   Yes
right x-coordinate of the right side of the view, in map layer coordinates   Yes
bottom y-coordinate of the bottom side of the view, in map layer coordinates   Yes
top y-coordinate of the top side of the view, in map layer coordinates   Yes

<app_vars>

This section specifies information about any application variables defined for this application. An app_var is a global variable that can be read or written to by a plug-in, allowing for global information to be used in an application.  By default, all exposed model outputs are treated as app_vars without any action on the part of an application developer; defining application variables in an envx file provides additional app_vars above and beyond those exposed as model outputs.  Application variables can be included in policy site attributes and other queries used through Envision and its plug-ins. The <app_vars> tag has no attributes; application variables are defined with individual <app_var> child tags contained within the parent <app_vars> tag.

Attributes for the <app_var> tag are defined below.

Attribute Name Definition Values Required?
name Name of the metagoal. It can contain spaces string Yes
description Description of the application variable string No
value A floating point value specifying the value of the variable
floating point value Yes.
timing Indicate if and when the variable is  updated. 0=no autoupdate. The value is constant, or a plugin controls this value.
1=evaluate at the beginning of a time step only,
2=evaluate at the end of a time step only,
3=evaluate both at the beginning and end of a time step.
No, defaults to 3.
fieldname Specifies whether the variable  reserves a column in the IDU database for it’s own use. If a column name is specified, a column in the IDU databased is reserved for this variable. If the column doesn’t exist, it is created. If left blank, no column is reserved. string No (defaults to no column reserved)

<models>

This section specifies information about the plug-in models used by the application. Each model is specified in its own <model> tag, which are defined with the following attributes:

Attribute Name Definition Values Required?
name Name of the model. stringYes
path The full path/filename to the DLL. If the DLL is in the default directory (typically where the ENVISION.exe file is located), only the file name is required. string Yes
id A unique integer identifier for the model. The ID is used to distinguish multiple models contained with a common DLL.  If the plug-in only exposes a single model, then this is optional.  If specified, it must be consistent with the model ID's exposed by the plug-in integer No, unless multiple models are defined by a plug-in.  Defaults to -1.
use flag indicating whether to load/use this model in the current session 0=don’t use this model
1=use this model
No, defaults to 1 (use)
freq Time step for calling the model during a run.  Currently unused (reserved for future use). real number No, defaults to 1 year
timing Specifies whether the model is executed at the beginning of a step (prior to actor decision making) or at the end of a step (after actor decision-making)  See the Envision Flow Chart for more information about execution control of plug-in models. 0=run before actor decision-making
1=run after actor decision-making
No, defaults to 0 (execute at start of time step)
fieldname Specifies whether the model reserves a column in the IDU database for it’s own use. If a column name is specified, a column in the IDU databased is reserved for this model. If the column doesn’t exist, it is created. If left blank, no column is reserved. Generally this is not used. string No
initInfo A string that is passed to the model during its Init() call.  For many plug-ins, this is the path to the plug-in's configuration file. string Depends on the plug-in model referenced

<evaluators>

This section specifies information about the plug-in evaluators used by the application. Each evaluators is specified in its own <evaluator> tag, which are defined with the following attributes:

Attribute Name Definition Values Required?
name Name of the evaluators. stringYes
path The full path/filename to the DLL. If the DLL is in the default directory (typically where the ENVISION.exe file is located), only the file name is required. string Yes
id A unique integer identifier for the evaluator. The ID is used to distinguish multiple evaluators contained with a common DLL.  If the plug-in only exposes a single evaluator, then this is optional. If specified, it must be consistent with the model ID's exposed by the plug-in integer No, unless multiple evaluators are defined by a plug-in.  Defaults to -1.
use flag indicating whether to load/use this evaluator in the current session 0=don’t use this evaluator
1=use this evaluator
No, defaults to 1 (use)

Time step for calling the evaluator during a run.  Currently unused (reserved for future use). real number No, defaults to 1 year
timing Specifies whether the evaluator is executed at the beginning of a step (prior to actor decision making) or at the end of a step (after actor decision-making)  See the Envision Flow Chart for more information about execution control of plug-in evaluators. 0=run before actor decision-making
1=run after actor decision-making
No, defaults to 0 (execute at start of time step)
fieldname Specifies whether the evaluator reserves a column in the IDU database for it’s own use. If a column name is specified, a column in the IDU databased is reserved for this evaluator. If the column doesn’t exist, it is created. If left blank, no column is reserved. Generally this is not used. string No
initInfo A string that is passed to the evaluator during its Init() call.  For many plug-ins, this is the path to the plug-in's configuration file. string Depends on the plug-in model referenced

<visualizers>

This section specifies information about the visualizers used by the application. Each visualizer is specified in its own <visualizer> tag; each entry consist entirely of non-whitespace characters, with the exception of “Init Function Info” and “Name”. Visualizer descriptors include the following attributes:

Attribute Name Definition Values Required?
name Name of the visualizerstringYes
path The full path/filename to the DLL. If the DLL is in the default directory (typically where the ENVISION.exe file is located), only the file name is required. string Yes
id A unique integer identifier for the visualizer. The ID is used to distinguish multiple visualizers contained with a common DLL. integer No, defaults to
 -1
use flag indicating whether to load/use this visualizer in the current session 0=don’t use this visualizer 1=use this visualizer No, defaults to 1 (use)
type A flag indicating how the visualizer is used in ENVISION 1= this is an input visualizer
2 = this is a run time visualizer
4 = this is a post-run visualizer
Yes
initInfo A string that is passed to the visualizer during its Init() call string No

<metagoals>

This section specifies information about any metagoals defined for this application. “Metagoal” is a broad term used in Envision to define goals that are expressed as outputs of evaluative models, policy scores, and actor values. While not required, metagoals are a useful mechanism to connect actors, policies, and evaluative models.

Attributes for the <metagoal> tag are defined below.

Attribute Name Definition Values Required?
name Name of the metagoal. It can contain spaces string Yes
model Name of associated eval model, if used in altruistic decision-making. This must correspond to entry in the <eval_models> section described above.   string Yes is this metagoal isused in altruistic decision-making
decisionUse Indicates how the metagoal is used in Envision
0=don't use in decision
1=use in actor self-interest (value) decision only
2=use in altruistic decision only
3=use in both
Yes.

<lulcTree>

The <lulcTree> section contains information on the Land Use/Land Cover (LULC) class hierarchy employed for the application. Up to four tiers can be defined. These are, by convention, not requirement, generally referred to as LULC_A, the most highly aggregated version of the LULC classes, through LULC_D, the most highly articulate LULC classes. Each more detailed class must nest within the classes defined at the level above it, forming a hierarchical LULC “Tree”. Applications must define at least one tier of LULC descriptors. Any LULC classification scheme can be used, as long as it is placed within this hierarchical tree structure.

The LULC hierarchy can be defined within the <lulcTree> tag in two ways.  First, using child <classfication> tags (defined below) directly embedded within the <lulcTree> tag in the envx file, and second, in a external XML file.  In the former case, no additional attributes are specified in the <lulcTree> tag, just child <classification> nodes.  In the latter case, the path of the file is provided  using the form <lulcTree file="pathToMyFile.xml" /> and no child tags are needed.

  An example LulcTree file (coded with the LULC classes defined by the 2001 National Land Cover Database (NLCD) classification scheme) is available here.

The format of the lulcTree XML is straightforward. Each tier of the classification is defined within an Xml <classification> tag. Classification tag attributes include the name of the class, which generally corresponds to the database column in the IDU shape coverage that holds this classification code for each IDU polygon, and the level of the class, corresponding to the level of this classification in the LULC three-tier hierarchy. For example, if the classification corresponds to a database column called LULC_A representing the top tier (most aggregated) level in the lulcTree, then the classification name attribute will be “LULC_A”, and the level attribute will be “1”.

Attributes for the parent <classification> tag are defined below.

Attribute Name Definition Values Required?
name Database column name for this level of classification (e.g. LULC_A) string Yes
level The heirarchical level of this classification 1=top,
2=second,
3=third, etc.string
Yes
fieldname The IDU database field name associated with this LULC level string No, defaults to name value if not present

Within a <classification> tag, each LULC class is defined with a <lulc> tag. This tag defines specific lulc codes for a given level in the classification hierarchy. Each <lulc> tag has attributes giving the classification code for the class (id), and a text description of the class (name). Additionally, with the exception of the top level (level=1) classes, each <lulc> include the classification code of its parent class in the LULC hierarchy (parentID).

Attributes for the <lulc> tag are defined below. These are child tags of the parent <classification> tag.

Attribute Name Definition Values Required?
id The classification code for this class. It should be unique within its LULC classification level, e.g. each LULC_A class ID should be unique. This is the code that is stored in the IDU database and referred to in Policy Site Attributes and Outcome strings  integer LULC code Yes is this metagoal isused in altruistic decision-making
parentID The classification code for the parent of this class. (not included in top-level classes, Integer LULC code Required for second and below tier classes), no required for top level in heirarchy
name Land Use/Land Cover class name (optional, this generally is specified in a fieldInfo file instead of here) string No

<actors>

The <lulcTree> section contains information on the Land Use/Land Cover (LULC) class hierarchy employed for the application. Up to four tiers can be defined. These are, by convention, not requirement, generally referred to as LULC_A, the most highly aggregated version of the LULC classes, through LULC_D, the most highly articulate LULC classes. Each more detailed class must nest within the classes defined at the level above it, forming a hierarchical LULC “Tree”. Applications must define at least one tier of LULC descriptors. Any LULC classification scheme can be used, as long as it is placed within this hierarchical tree structure.

The LULC hierarchy can be defined within the <lulcTree> tag in two ways.  First, using child <classfication> tags (defined below) directly embedded within the <lulcTree> tag in the envx file, and second, in a external XML file.  In the former case, no additional attributes are specified in the <lulcTree> tag, just child <classification> nodes.  In the latter case, the path of the file is provided  using the form <lulcTree file="pathToMyFile.xml" /> and no child tags are needed.

  An example LulcTree file (coded with the LULC classes defined by the 2001 National Land Cover Database (NLCD) classification scheme) is available here.

The format of the lulcTree XML is straightforward. Each tier of the classification is defined within an Xml <classification> tag. Classification tag attributes include the name of the class, which generally corresponds to the database column in the IDU shape coverage that holds this classification code for each IDU polygon, and the level of the class, corresponding to the level of this classification in the LULC three-tier hierarchy. For example, if the classification corresponds to a database column called LULC_A representing the top tier (most aggregated) level in the lulcTree, then the classification name attribute will be “LULC_A”, and the level attribute will be “1”.

Attributes for the parent <classification> tag are defined below.

Attribute Name Definition Values Required?
name Database column name for this level of classification (e.g. LULC_A) string Yes
level The heirarchical level of this classification 1=top,
2=second,
3=third, etc.string
Yes
fieldname The IDU database field name associated with this LULC level string No, defaults to name value if not present

Within a <classification> tag, each LULC class is defined with a <lulc> tag. This tag defines specific lulc codes for a given level in the classification hierarchy. Each <lulc> tag has attributes giving the classification code for the class (id), and a text description of the class (name). Additionally, with the exception of the top level (level=1) classes, each <lulc> include the classification code of its parent class in the LULC hierarchy (parentID).

Attributes for the <lulc> tag are defined below. These are child tags of the parent <classification> tag.

Attribute Name Definition Values Required?
id The classification code for this class. It should be unique within its LULC classification level, e.g. each LULC_A class ID should be unique. This is the code that is stored in the IDU database and referred to in Policy Site Attributes and Outcome strings  integer LULC code Yes is this metagoal isused in altruistic decision-making
parentID The classification code for the parent of this class. (not included in top-level classes, Integer LULC code Required for second and below tier classes), no required for top level in heirarchy
name Land Use/Land Cover class name (optional, this generally is specified in a fieldInfo file instead of here) string No
Additionally, policies, actors and scenarios are defined in the ENVX file.

The Integrated Decision Unit (or IDU) shape file is a GIS coverage that contains the polygons that form the decision units for ENVISION. It must conform to ESRI’s Shape File specification. The polygon geometry can be defined by the application developer at what ever scale and with whatever geometry is appropriate for the application. If the decisions to be modeled are made at a tax lot (parcel) level, then parcels might be an appropriate IDU. If some other decision unit is appropriate, the IDU geometry should reflect that. The IDU Shape file to use for a given application of ENVISION is specified in the [layers] section of the Project file. Note that multiple layers can be specified in this section; the first is assumed to be the IDU coverage. All IDU attributes must be contained in the IDU coverage – multiple IDU coverages in a single application are not currently supported in ENVISION. It is important to emphasize that ENVISION can ONLY deal with landscape information that is represented in the IDU coverage. The IDU coverage should contain any attributes that are needed by any of the following:

Additionally, there are are a small number of attibute fields required to be present in the IDU coverage, specified as follows. These can be added in with any software capable of manipulating Shape file databases; examples include ArcGIS, GRASS, and QGIS. Additionally ENVISION has the ability to add these fields automatically or manually (see Data Preparation Functions for more information.)

Attribute Name Data Type Description
LULC_A LULC_B LULC_C Integer Land Use/Land Cover (LULC) classes. ENVISION employs a n-tier hierarchy of LULC classes, with up to four tiers specified. LULC_A is the top-tier class, representing the most aggregated LULC descriptors. LULC_B is a more articulated version, and LULC_C is the most articulated version of the LULC classes. This concept of an LULC hierarchy is employed to allow Site Attributes and Outcomes to be specified at various levels of generality. The specific classes used in each classification level can be defined by the application in a comma-delimited file specified in the lulcTree setting in the Project file. If only LULC_C attributes are specified in the IDU coverage, ENVISION can populate the LULC_B and LULC_A fields automatically – see Data Preparation Functions in the manual for more information. LULC_A is required at a mimimum; LULC_B and LULC_C are optional. AREA Numeric, Single or Double Contains the area of the IDU. This can be populated automatically by ENVISION - – see Data Preparation Functions in the manual for more information.

LULC_A is required at a minimum; LULC_B and LULC_C are optional.
POLICY Integer ENVISION uses this column to store the most recent Policy ID to be applied to an IDU. It does not need to be populated by the developer; it just needs to exist in the IDU coverage.
POLICYAPPS Integer ENVISION uses this column to store the most number of policy applications made to an IDU. It does not need to be populated by the developer; it just needs to exist in the IDU coverage.
LASTD Integer ENVISION uses this column to store the year in which the last actor decision was made for this IDU. It does not need to be populated by the developer; it just needs to exist in the IDU coverage.
NEXTD Integer ENVISION uses this column to store the year in which the next actor decision is scheduled for this IDU. It does not need to be populated by the developer; it just needs to exist in the IDU coverage.
STARTLULC Integer ENVISION uses this column to "remember" the initial LULC_C value of the IDU. This columns needs to be present, but ENVISION populates it automatically.
UTILITYID Integer This is only used if Actor decision-making based on utility is enabled. In that case, an autononous processes should be defined that populates this field with the policyID of the policy that maximizes utility for the given IDU.