Envision Input Files

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:

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

Individual sections of the Project file are described below.


<settings>

Attribute NameDefinitionValuesRequired?
Envision Environment
debug ReservedNo
logMsgLevel Level of logging messages0=log everything (default),
1=log critical events,
2= log nothing
No
noBuffering Determines where buffering is suported in policy outcome0=buffering supported
1=buffering not supported (default)
No
parallelIf enabled, allows evaluative models and autonomous processes to be run in parallel if multiple CPU cores are available0 = 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
spatialIndexDistanceMinimum 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
areaCutoffMinimum 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 sizeNo
policyPrefenceWtdefault weight used for policy scoring preferences during actor decision-making0 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 returnsNo
mapUnits Map Units of the IDU coverage‘feet’, ‘meters’,’degrees’,’unknown’ (default)No
ConstraintsReservedNo
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')
multiRunIterationsDefault 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
actorInitMethodMethod used to initialize Actor weights0 = 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
actorAssociationsReserved for future useNo
loadSharedPoliciesDetermines whether shared policies are loaded from the policy database0=don’t load shared policies
1=load shared policies (default)
No
actorDecisionElementsIndicates 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
actorDecisionMethodDetermines whether actors select policies proabilistically or always selecting the “best” policy1=probabilistically select policies based on scores (default) 2= always pick policy with the highest score
dynamicActorsReserved for future useNo
shuffleActorPolysIf enabled, the polygon order by which actors make decisions is randomized at each step0 = 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
exportMapIntervalDefault 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
exportBmpIntervalDefault 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
exportBmpPixelSizeCell size (in map units) for exporting bitmaps (.bmp). Only used if exportMapInterval > 0Must be a positive value, in map units
exportBmpColsString 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
exportOutputsEnables automatic export of CSV files containing model results and exposed variables at the end of a run0 = 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 run0=dont' export delta array (default)
1=export delta array
No
exportDeltaColsString 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 arrayNo

 

<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 NameDefinitionValuesRequired?
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 NameDefinitionValuesRequired?
name A name associated with the coverage.Any stringYes
path The path to the coverage on diskYes
initField Initial field to be displayed after the coverage is loaded into EnvisionAny valid fieldNo (defaults to first field)
overlayFields No
color Color for drawing polygon/line edges, expressed as an RGB triplet, i.e. r,g,bExample: '0,0,0' results in a black polygon/line edgeNo, 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 featuresAny valid string fieldNo (labels won't be drawn)
labelFont The name of the font used to draw labelsNo, defaults to 'Arial'
labelSize The size of the labels to be drawnNo, defaults to '120'
labelColor Color for drawing labels, expressed as an RGB triplet, i.e. r,g,bExample: '0,0,0' results in a black fontNo, defaults to '255,255,255' (white)
labelQuery A spatial query used to determine which IDU's should be used for labelingAn valid spatial queryNo, 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 NameDefinitionValuesRequired?
nameName of the  zoom.  This appears in the "Zoom to" dialog box in the Envision interfacestringYes
leftx-coordinate of the left side of the view, in map layer coordinates Yes
rightx-coordinate of the right side of the view, in map layer coordinates Yes
bottomy-coordinate of the bottom side of the view, in map layer coordinates Yes
topy-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 NameDefinitionValuesRequired?
name Name of the metagoal. It can contain spacesstringYes
description Description of the application variablestringNo
valueA floating point value specifying the value of the variable
floating point valueYes.
timingIndicate 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.
fieldnameSpecifies 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.stringNo (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 NameDefinitionValuesRequired?
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.stringYes
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-inintegerNo, unless multiple models are defined by a plug-in.  Defaults to -1.
use flag indicating whether to load/use this model in the current session0=don’t use this model
1=use this model
No, defaults to 1 (use)
freqTime step for calling the model during a run.  Currently unused (reserved for future use).real numberNo, defaults to 1 year
timingSpecifies 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)
fieldnameSpecifies 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.stringNo
initInfoA 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.stringDepends 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 NameDefinitionValuesRequired?
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.stringYes
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-inintegerNo, unless multiple evaluators are defined by a plug-in.  Defaults to -1.
use flag indicating whether to load/use this evaluator in the current session0=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 numberNo, defaults to 1 year
timingSpecifies 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)
fieldnameSpecifies 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.stringNo
initInfoA 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.stringDepends 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 NameDefinitionValuesRequired?
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.stringYes
id A unique integer identifier for the visualizer. The ID is used to distinguish multiple visualizers contained with a common DLL.integerNo, defaults to
 -1
use flag indicating whether to load/use this visualizer in the current session0=don’t use this visualizer 1=use this visualizerNo, defaults to 1 (use)
type A flag indicating how the visualizer is used in ENVISION1= this is an input visualizer
2 = this is a run time visualizer
4 = this is a post-run visualizer
Yes
initInfoA string that is passed to the visualizer during its Init() callstringNo

<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 NameDefinitionValuesRequired?
name Name of the metagoal. It can contain spacesstringYes
model Name of associated eval model, if used in altruistic decision-making. This must correspond to entry in the <eval_models> section described above.   stringYes is this metagoal isused in altruistic decision-making
decisionUseIndicates 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 NameDefinitionValuesRequired?
name Database column name for this level of classification (e.g. LULC_A)stringYes
level The heirarchical level of this classification1=top,
2=second,
3=third, etc.string
Yes
fieldname The IDU database field name associated with this LULC levelstringNo, 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 NameDefinitionValuesRequired?
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 codeYes is this metagoal isused in altruistic decision-making
parentIDThe 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)stringNo

<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 NameDefinitionValuesRequired?
name Database column name for this level of classification (e.g. LULC_A)stringYes
level The heirarchical level of this classification1=top,
2=second,
3=third, etc.string
Yes
fieldname The IDU database field name associated with this LULC levelstringNo, 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 NameDefinitionValuesRequired?
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 codeYes is this metagoal isused in altruistic decision-making
parentIDThe 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)stringNo
Additionally, policies, actors and scenarios are defiend in the ENVX file.