id User’s Manual

Timothy C. Haas

Lubar School of Business

University of Wisconsin at Milwaukee

haas@uwm.edu

July 12, 2018

1 Introduction

This software system implements components of the proposed Ecosystem Management Tool(EMT) being developed by the author. In this Tool, stochastic models of group decisionmaking and models of wildlife populations are constructed in the form of influence diagrams(IDs). All hardware and operating system mechanics for running id are described in aseparate document located at www4.uwm.edu/people/haas/idusers/. See Haas (2011,ch. 5) for the development goals of the id software system.

2 EMT User Interface

To ensure ease of use, the user interface is a critical aspect of the EMT. A user (hereafteranalyst) who has only modest statistical training should be able to ask the EMT for aparticular ecosystem analysis. In addition, the EMT should also be able to generate at leastpart of the publication quality report the analyst is almost always ultimately interested inas a final product of the analysis.

Many ecosystem data analyses are incremental and sequential – a preliminary analysisis performed and then a sequence of analyses are executed, each only minimally differentfrom the original analysis. Because of this sequential nature of doing ecosystem analyses,it can be more convenient to have a natural language interface to the EMT rather than agraphical user interface (GUI). Therefore, the EMT described here uses a language devel-oped to describe, estimate, and evaluate an influence diagram and will be referred to asthe id language. Once learned, the id language allows the analyst to quickly formulate thenecessary instructions to the EMT for both performing the desired analysis and generatingall necessary figures and tables for the report.

3 General Structure of the id Language

All hardware and operating system mechanics for running id are described at:www4.uwm.edu/people/haas/idusers. The language presented below is a fully-functional

1

language for performing statistical analyses needed to support ecosystem management de-cision making.

3.1 Language overview

Following Johnson (1994), the id language is defined by a hierarchical vocabulary of mainwords, qualifiers of those words, and set of n-ary assembly relations.

There are only four main words: influence diagram, node, context, and report. Thelatter three words have several qualifiers and all have several n-ary assembly relations (seeTables 1-6). Qualifiers specify particular types of a main word’s entity, and relations createa mapping between user-created inputs and outputs that are associated with the qualifiedmain word.

The user prepares an input file consisting of statements in this language. Each groupof records starts with one of the main words followed by some number of qualifiers and/orrelations. This language, similar to the one proposed by Lubinsky (1990), is intended to bea high-level, non-programming language for expressing statistical models and analyses thatpersons with only modest technical training can use to express political-ecological systemsand find plans to manage the associated ecosystem.

The entire vocabulary of this language appears in Tables 1-6. In these Tables and thefollowing descriptions of the constituent relations, a Document Archive Number (DAN) isa unique identification number assigned by the database builder to a news article for thepurposes of building a group actions database. For details of how such a database is built,see Haas (2011, ch. 9).

2

Word-Level Relations Qualifiers Qualifier Relations

Main word: influence diagram

idfile(id file name

plotting string

country name)

Main word: node

names(node name Determ Contin parameters(n parm-1 ... parm-n)

short name)

values(n value-1 ... value-n) Determ Decision parameters(n parm-1 ... parm-n)

parents(n short name-1 ... Determ Discrete

short name-n) Determ Frctn parameters(n parm-1 ... parm-n)

memory(short name) Determ Labeled parameters(n parm-1 ... parm-n)

Determ Linear parameters(n parm-1 ... parm-n)

Determ Loss parameters(n parm-1 ... parm-n)

Determ Root

Determ Thrshld parameters(n parm-1 ... parm-n)

Discrete

Gamma parameters(n parm-1 ... parm-n)

GLOMAP parameters(n parm-1 ... parm-n)

Logit parameters(n parm-1 ... parm-n)

Lognormal parameters(n parm-1 ... parm-n)

LOMAP parameters(n parm-1 ... parm-n)

Normal parameters(n parm-1 ... parm-n)

SDE parameters(n parm-1 ... parm-n)

Table 1: Qualifiers and relations for the id language main words influence diagram, and

node. Arguments to relations are italicized.

3

Qualifier relation Argument(s)

Qualifier: settings

real-world type

phenomenon type

geographic window min long max long min lat max lat

ecosystem nodes n label-1 ... label-n

inputs n (node-1 value) ... (node-n value)

(Time sdebegintime tmin tmax) (node-i all )

management policy policy

initial actions m (actor-1 action-1 n1 target-1 . . . target-n1)

. . . (actor-m action-m nm target-1 . . . target-nm)

region m region-1 . . . region-m

Qualifier: files

EMAT files definitions-filename equivalence-sets-filename

parameter files old/new hypothesis-filename estimates-filename

initial-values-file-name MPEMP-filename

boundaries file filename is-longitude-boolean

sites file filename

gis layer files m filename-1 . . . filename-m

observed actions filename

history file

data file filename

output files graph-plot-filename report-filename

parameter-estimates-filename

node output files xy-points-filename abundance-filename

actions file filename

Table 2: Qualifiers and relations for the id language main word: context.

4

Relation Arguments

Qualifier: prepare data

read NWS data

convert data lng-lat-filename analysis-filename tmin tmax xy-filename

convert eos data eos-lng-lat-filename xy-filename min-longitude

max-longitude min-latitude max-latitude time #rows

#cols min-val max-val background-value variable-name

convert boundary n lng-lat-filename-1 . . . lng-lat-filename-n

xy-filename #rows #cols

prepare raw group raw data-filename actions-history-data-filename

data check-level

gis tools lat-lng-point-filename m image-filename-1 . . .

image-filename-m

parse stories stories-filename accuracy-estimate-boolean

learn-mode-boolean starting DAN

groups-filename regions-filename

parsed-stories-filename actions-filename

rdbms database-name stories-filename groups-filename

regions-filename parsed-stories-filename SQL-query

build-option

compute risks abundance-filename risks-filename

find product themes

Qualifier: describe data

compare samples n (node-a1 node-b1) . . . (node-an node-bn)

Table 3: Relations for the prepare data, and describe data qualifiers of the id language’s

main word: report.

5

Relation Arguments

Qualifier: estimate

estimate nodes tbegin tend m (idname-1 n1 node-11 . . . node-n1)

. . . (idname-m nm node-1m . . . node-nm) cH

#MC realizations initsubstep1-boolean initsubstep2-boolean

maximize-boolean plots-only-boolean

ecosystem-calculations-boolean confidence-intervals-boolean

fit logits n node-1 ... node-n

prediction skill tbegin tend m

(idname-1 n1 node-11 . . . node-n1) . . .

(idname-m nm node-1m . . . node-nm) cH #MC realizations

find mpemp tbegin tend m (idname-1 n1 node-11 . . . node-n1)

. . . (idname-m nm node-1m . . . node-nm) cH

#MC realizations

cross-validation tmin tmax prediction option prediction time

find interdiction boundary-filename carcass-filename targets-data-filename

patrol route attributes-filename interdiction-routes-filename

route-generator-boundary-filename

route-generator-routes-filename generate-routes-boolean

update-routes-boolean

pursuit strategy targets-filename attributes-filename beginning-route-number

ending-route-number

reconstruct links-filename #groups centralities-only-boolean

social network #MC-realizations

Table 4: Relations for the estimate qualifier of the id language’s main word: report.

6

Relation Arguments

Qualifier: evaluate

id interactions begin time end time #MC realizations per ID

evaluate nodes n node-1 . . . node-n #MC realizations

optimal decision #MC realizations

surface short name min data-read time max data-read time

begin pred window time end pred window time

pred option #rows #cols grid type

volume short-name tmin tmax tpred prediction option

#rows #MC realizations

simulate MOC

find author student-documents-filename

clusters

Qualifier: display

plot graph m (n1 node-11 . . . node-n1) . . .

(nm node-1m . . . node-nm)

label regions PostScript file

overlay surface file PostScript file

display intervals n (low-1 high-1) . . . (low-n high-n)

interval labels n label-1 ... label-n

map levels n original level name-1 new-level-1

. . . original level name-n new-level-n

plot surface surface file PostScript-filename

plot actions plot type actions-history-filename PostScript-filename

history tbegin tend ymin ymax

xyplots filename ymin ymax

Table 5: Relations for the evaluate, and display qualifiers of the id language’s main

word: report.

7

Relation Arguments

Qualifier: sensitivity analysis

assess nodes tbegin tend m (idname-1 n1 node-11 . . . node-n1)

. . . (idname-m nm node-1m . . . node-nm)

#MC realizations

Qualifier: mc hypothesis test

nodes to estimate tbegin tend m (idname-1 n1 node-11 . . . node-n1)

. . . (idname-m nm node-1m . . . node-nm) cH

#MC realizations #subsamples

Table 6: Relations for the sensitivity analysis, and mc hypothesis test qualifiers of

the id language’s main word: report.

8

3.2 id Language File Example

Figure 1 contains an id language file for modeling the deposition of NO3 through precipi-tation with LOMAP spatial stochastic random variables.

Nitrate, Precipitation exampleof bivariate spatial prediction.node Xcoord x Determ_Decision

values(1 xcoord)

node Ycoord y Determ_Decisionvalues(1 ycoord)

node no3 no3 LOMAPparents(2 x y)values(1 no3)parameters(5 trnsfrm kmax vmodel itrend f_c)

node ppt ppt LOMAPparents(2 x y)values(1 ppt)parameters(5 trnsfrm kmax vmodel itrend f_c)

context settingsreal-world_phenomenon_type(ecosystem)

context filesdata_file(spatialpred.dat)parameter_files(old spatialpred-hyp.par spatialpred-est.par)boundaries_file(spatialpred.bln false)sites_file(sites.dat)output_files(spatialpred.ps spatialpred.html spatialpred.est)

report estimatecross-validation

report evaluatesurface(no3 0. 0. 0. 0. 2 9 1)

report displayplot_surface(sill.sgd fig2.ps)display_intervals(5 0. .15 .15 .3 .3 .45 .45 .6 .6 .75)interval_labels(5 ’.00-.15’ ’.15-.30’ ’.30-.45’ ’.45-.60’ ’.60-.75’)

report prepare_dataconvert_boundary(1 us.lgt us.bln 60. 130. 25. 52. 5 5)

Figure 1: id language file for modeling NO3 deposition through precipitation.

9

3.3 Structure of an id language input file

id uses one file to define an ID, called the id language file. This file contains all id languagestatements and is identified by its file extension .id. The structure of this file is as follows.

First section: all influence diagram, and node statements to define the IntID or IDmodel.

Second section: all context statements.

Third section: groups of report statements wherein each group begins with the mainword, report.

id detects that a group of report qualifiers has ended when either the end-of-file is reachedor another report statement is encountered. Only one report group is executed when idis run. Other analyses, described by other groups of report statements can be stored belowthe group to be executed. Use of this feature allows all analyses to be maintained in onefile.

In any of the relations of this language, if a character string is a number, enclose it insingle right quotes, e.g.interval labels(2 ’1.5-2.5’ ’2.5-3.5’).

3.4 Structure of an id language surface file

This file type is referred to as surface file in Tables 3-6. Its format is as follows:

Record 1: Grid-type (1 = rectangular, 2 = hexagonal) xmin xmax ymin ymax surface-minsurface-max.

Subsequent Records: x-value y-value surface-value status where status is 0 if (x-value,y-value) is inside the boundary and 1, otherwise.

4 The main words influence diagram and node

4.1 influence diagram

This main word specifies an id language file that, in-turn, describes one of the componentIDs of an IntIDs model. Its sole relation, idfiles expects strings for plot labels, and thecountry that the ID is associated with.

4.2 node

A node represents either a random (stochastic) variable or a deterministic variable. Thesevariables may be observable or latent. Random variables are called chance nodes. The ID

10

structure contains LISREL (Koster 1996) models which in turn, contain multivariate linearmodels. Such models can be represented in id with Determ Linear nodes.

Semiparametric and parametric spatio-temporal models are represented with LOMAP orGLOMAP nodes (see Haas (2002)). Hence, the collection of node words in an id languageinput file defines the stochastic model of the relationship between the dependent nodes andindependent nodes.

It is planned to include nonparametric models such as neural networks, classificationand regression trees, k-nearest neighbor classifiers as node distributions NN, Tree, and KNN,respectively.

4.2.1 node relations

These relations are not associated with a qualifier.

names: gives the node’s full name and a short abbreviation. Express node names with shortphrases and use “ ” to connect words. For the short name, use either an acronym orother abbreviation of the node name that is suitably short for graphical displays, say1-5 characters.

Arguments: node name, short name

values: gives the values that the node can take on.

Arguments: number of values (n), value-1, ... value-n.

parents: gives the parents of the node.

Arguments: number of parents (n), parent-1, ..., parent-n.

memory: gives the node whose distribution at the previous time step is to be used by thisnode.

Argument: short name.

4.2.2 node qualifiers

Determ Contin: a node that takes on a single continuous value for each combination of thevalues of its parents.

There is no parameter relation for this qualifier.

Determ Decision: a node with a user-specified list of values that are the different decisionoptions being considered.

There is no parameter relation for this qualifier.

Determ Discrete: a node that takes on a single discrete value for each combination of thevalues of its parents.

There is no parameter relation for this qualifier.

11

Determ Frctn: a node whose value is 0 if its sole parent is below a lower threshold, between0 and 1 if its parent is between the lower and upper thresholds, and 1 if the parentis above the upper threshold.

Arguments to parameter relation: lower threshold and upper threshold.

Determ Labeled: deterministic node whose values are labels indexed by the numericalvalue of its parent.

Arguments to parameter relation: label-1, . . ., label-m where the parent has m values.

Determ Linear: a node that is a deterministic, linear function of its parent:β1 + β2 × parent-value. Note that if a spatio-temporal covariance structure is desired,do not use this node type. Instead, use a LOMAP/GLOMAP type node that has the desiredcovariates and/or qualitative nodes as parents.

Arguments to parameter relation: β1 and β2.

Determ Loss: a deterministic quadratic loss function centered at β0 and scaled by β1.

Arguments to parameter relation: β0 and β1.

Determ Root: a deterministic root node (no parents).

There is no parameter relation for this qualifier.

Determ Thrshld: a node whose value is zero until the value of a parent node rises above aparameter threshold value, i.e., 0 if parent-value is less than threshold, 1 otherwise.

Arguments to parameter relation: threshold.

Discrete: the simple discrete chance node with a small (< 5) number of values.

There is no parameter relation for this qualifier.

Gamma: the Gamma chance node.

Arguments to parameter relation: shape and scale.

Logit: The Cumulative Logit model. A distribution is specified in the .par file by listingthe desired conditional distributions. This is accomplished by specifying the node’sdistribution at 3 values of the parent node. id finds parameter values that cause themodel to match these specified conditional distributions. This search is started atall coefficients set to zero. This mechanism allows the user to specify a logit modelwithout having to express a desired set of logit probabilities in terms of correspondingcoefficient values.

This model is: logitj = ln[P (Y ≤ j)/P (Y > j)] = αj+f(β,X), j = 1, . . . , J−1 whereX is a vector of m parent values, and β is the vector of corresponding coefficients.For J = 3, the probabilities for each level of Y are: p1 = exp(logit1)/(1+exp(logit1))and p2 = (exp(logit2)− p1(1 + exp(logit2)))/(1 + exp(logit2)). The functions, f() ofthe parent node are hand-coded into the method Beliefs.complogits ().

Arguments to parameter relation: α1, . . ., αJ , β1, ... βm.

12

LOMAP, GLOMAP: multivariate spatio-temporal stochastic processes. LOMAP uses a semi-parametric moving cylinder model for the trend along with local covariance structuremodels while GLOMAP uses a kernel-weighted sum of LOMAP models to provide a globalmodel of the spatio-temporal process’s trend and covariance structure.

Arguments to parameter relation:

ttype: the value 1 indicates one-time-step-ahead forecasting, 2 indicates spatio-temporal interpolation.

kmax: number of spatial lags for the spatial covariogram.

kmaxt: number of temporal lags for the temporal covariogram.

vmodel: semivariogram model specification. 0 gives a nugget-only semivariogram; 1,a spherical; and 2 an exponential.

itrend: order of the spatio-temporal trend polynomial: 4 for a zero-order polynomial;5 for a first-order polynomial; and 6 for a second-order polynomial.

s frac: fraction of monitoring sites (spatial locations) to use in a LOMAP predictioncylinder. Referred to as fc in Haas (1995).

t frac: temporal length of a LOMAP prediction cylinder.

trnsfrm: the value 0 produces no transformation to the residual process, and 1produces a transformation (see Haas (2002)).

nmstmixcntr: number of GLOMAP components (GLOMAP only).

Term definitionsThe following is based on Haas (1995). The term prediction will refer to inferenceon random quantities at any location and time, and the term estimation will referto inference on fixed but unknown parameters.

Let the spatial coordinates of locations in the spatio-temporal space be given by(x, y) and the temporal coordinate by t. A spatio-temporal location is designatedby x = (x, y, t)′, and n is the total number of spatio-temporal observations. Letfc ∈ (0, 1) be the fraction of n that is used for a prediction. Define nc ≡ nfc tobe the number of observations used to calculate the prediction at x0. Call thespatio-temporal space that holds the nc observations used to predict the processat x0, the prediction cylinder.

The cylinder’s nc observations are found as follows.

Step 1: Let tearliest and tlatest be the time of the earliest and latest observation inthe data set, respectively. The temporal range of the cylinder is fixed at a user-selected value, mT <= tlatest−tearliest. The cylinder’s temporal interval is [tL, tU ]where mT = tU−tL. The upper limit, tU is defined to be min{tlatest, t0+mT/2}.The lower limit, tL equals max{tearliest, tU −mT}. It is assumed that mT is largeenough so that nc < nI .

Step 2: The nI observations found in step 1 are sorted on the primary sort keyof

13

‖ (x0, y0)′ − (x, y)′ ‖ and on the secondary sort key of |t0 − t|, i.e., the sites

are sorted according to their spatial distance from (x0, y0)′ and all observations

taken at a particular site are sorted by their temporal distance from t0. Let thislist of sorted observations be numbered 1 through nI .

Step 3: The cylinder’s observation set is defined to be the first nc of thesesorted observations.

Normal, Lognormal: the normal and lognormal chance nodes, respectively.

Arguments to parameter relation: µ and σ2.

SDE: In this version of id, if a system of SDE’s is part of the model, the mathematicalforms of the trend and diffusion matrices need to be programmed in the a () andb () methods, respectively in the JAVA source file, Sdesol.java. In the sourcedistribution of id, the cheetah viability SDE system is coded in this file. Specifically,the four SDE equations on pages 113 through 115 of Haas (2001) are coded withinSdesol.java as follows:

static double a_(double nodevals[][][], double alpha[], double beta[],int k, double tn, double yn[], int dst) {

// Evaluates the trend vector.int i;double val = 0., trend, y;if (k == 1) {

y = yn[k - 1];val = y * (alpha[0] - y);

} else if (k == 2 || k == 3) {y = 2. * yn[k - 1] - 1.;val = -.5 * (alpha[k - 1] + beta[k - 1] * beta[k - 1] * y) *

(1. - y * y);} else if (k == 4) {

trend = yn[1] * (1. - Math.pow(alpha[3], alpha[4] * yn[3])) * yn[3];trend -= yn[2] * yn[3];// Get the current Carrying Capacity node value.i = Getmodl.getndnm_("CarCap");alpha[5] = nodevals[Beliefs.locnm][1][i - 1];trend -= (yn[1] - yn[2]) * yn[3] * yn[3] / alpha[5];val = trend;

}return val;}static double b_(double beta[], int i, int j, double tn, double yn[],

int dst) {// Evaluates the (i, j)^th component of the diffusion matrix.double val = 0., y;if (i != j) {

val = 0.;} else if (i == 1) {

val = beta[0] * yn[0];} else if (i == 2 || i == 3) {

y = 2. * yn[i - 1] - 1.;val = beta[i - 1] * (1. - y * y);

} else if (i == 4) {val = beta[3];

14

}return val;}

15

To solve a different set of SDEs, modify Sdesol.java as necessary and recompile torebuild the JAVA class file, Sdesol.class.

Arguments to parameter relation: SDE dependent.

5 The main word context

This word sets the context for the report’s analysis. Its qualifiers are as follows.

5.1 Relations for the settings qualifier

This qualifier provides information needed to narrow the analysis to a particular situationunder study.

real-world phenomenon type: currently, president, EPA, rural resident, pastoralist, ngo,and ecosystem are recognized.

ecosystem nodes: Specifies the node names that are the output nodes of the ecosystemID.

geographic window: gives a rectangle in geographic (decimal) units for the analysis. Anypoints in a conversion activity that are outside this window are ignored. The boundingbox defined by the convert boundary relation over-rides these values.

management policy: Ecosystem management policy that is applied over the entire timespan of the IntIDs simulation.

initial actions: gives the actors and output actions that initiate an IntIDs simulation.

inputs: specifies the values of the conditioning nodes. If the value of a discrete inputs

node is the reserved keyword all , then each value of this node in turn is used asthe conditioning value. Use this capability to compute model outputs over each andevery region in a spatial data set. Such a node needs to be the first node to appear inthis list. For the special case of the node “Time,” specify the beginning time for anSDE solution, the minimum conditioning time, and the maximum conditioning timewith:

“Time” sdebegintime tmin tmax.

If no SDEs are in the ID, sdebegintime is ignored. For a spatial-only LOMAP/GLOMAPtype node, computations will be performed for each unique time value in the samplebetween these minimum and maximum values. For a spatio-temporal LOMAP/GLOMAPtype node, a single computation using all observations between these two values willbe performed.

16

5.2 Relations for the files qualifier

This qualifier gives names of various input and output files needed for the analysis.

EMAT files: delineates a taxonomy of political-ecological actions, referred to as the ecosys-tem management actions taxonomy (EMAT) developed by Haas (2011, pp. 123-141).The EMAT is defined in-part by three sentence components: m-word verbs, directobject phrases, and prepositional phrases. Letting m be a positive integer, an m-wordverb subsumes single-word verbs (either regular or irregular), and multi-word verbs(these use more than one word to convey their meaning, e.g. “picked up”). Eachaction in this taxonomy has been parsed into three equivalence sets: a set of semanti-cally equivalent m-word verbs, a set of semantically equivalent direct object phrases,and a set of semantically equivalent prepositional phrases, respectively.

gis layer files: GIS layers for use in stochastic movement model analyses.

observed actions history file: data on political actions for use in simulator parameterestimation.

node output files: first file holds simulated values of a spatio-temporal node, and thesecond file holds abundance values simulated over a given time interval.

parameter files: gives the file names of the hypothesis, initial values, and estimated(consistent) parameter files that define the ID’s nodes. The parameter values associ-ated with the model defined in a name.id file are listed in the parameters file whichhas the file extension .par. “name” is any alphanumeric string acceptable to theuser’s file system. The user is responsible for creating separate parameter files tohold hypothesis and estimated values, respectively. A suggested naming conventionis name-hyp.par, name-init.par, and name-est.par. id writes analysis results to thereport file.

The results of a run to find the Most Practical Ecosystem Management Plan (MPEMP)are written to MPEMP file name.

When LOMAP/GLOMAP type nodes are present, semivariogram parameter estimates arewritten to the file name.est.

boundaries file: gives the file name containing spatial boundary files.

sites file: gives the monitoring site locations file name.

data file: gives the data file name. This file contains non-action history observations.The form of this file’s name is name.dat. It consists of observations on one or more ofthe ID’s nodes and is organized as stacked sets of records, one stack for each observedchance node. Say there are ni observations on the ith observed chance node. Therecords for this node are:

17

1. Record 1: A sequence of deterministic node short names plus the observed chancenode’s short name. These short names can be in any order but must be separatedby at least one space.

2. Record 2: The word “begin”

3. Records 3 through 2 +ni: values on the nodes listed in record 1 and in the sameorder as the record 1 sequence.

4. Record 3 + ni the word “end”

This data file form allows chance nodes to be irregularly and non-coincidentally ob-served in space and time.

output files: gives file names for the report file and the file containing selected parameterestimates.

6 The main word report

This word specifies the details of the report’s analysis. Qualifiers are as follows.

6.1 Relations for the prepare data qualifier

This qualifier prepares data files for subsequent analyses.

convert data: converts a longitude-latitude data file to an x, y data file.

convert eos data: converts an Earth Observation System (EOS) longitude-latitude datafile to an x, y data file. The arguments file min longitude, file max longitude,file min latitude, file max latitude, #rows, #cols, min val, max val, and background valcan be found in the header (.hdr) file that ModisTool creates when it reads the .hdffile obtained from the EOS data center. ModisTool can be downloaded for free fromthe EROS Data Center athttp://lpdaac.usgs.gov/tools/modis/register.asp. In this header file, useNLINES for the #rows and NSAMPLES for the #cols. If DATA TYPE is not INT16,the JAVA source code file Eosdata.java will need to be modified accordingly. Run-ning ModisTool is largely self-explanatory but be careful to select a geographic

projection and a raw binary file for the output.

convert boundary: converts a longitude-latitude boundary file to an x, y boundary file.This relation also writes a #rows-by-#cols longitude-latitude grid that overlays thebounded region. The boundaries and grid are plotted in the PostScript file “lng-latgrd.eps.”

prepare raw group data: reads a data file of group actions and creates an actions historyfile with actions translated into Ecosystem Management Actions Taxonomy (EMAT)

18

categories (see Chapter 9). The relation’s parameter, check level takes on the values“lowcheck” or “highcheck.” The latter provides more complete printing while the fileis being translated.

gis tools: starts an interactive session to perform GIS operations. Below, these opera-tions or tools will be referred to as id’s GIS tools. When id is run with this relation,menus allow the user to perform the following tasks:

1. Display geographic images, e.g. maps.

2. Perform on-screen digitizing. Having this capability relieves the EMT-maintainingorganization from having to purchase and maintain a digitizing tablet. Thiscapability functions by having the user first enter the latitude-longitude coordi-nates of at least three points on the image. Then, id computes the minimum-error transformation between the image and the latitude-longitude coordinatesystems. Then, the user is free to use the mouse to indicate points on a path thatrepresents either a region of the image or a surface of constant (user-entered)value.

3. Convert a data set expressed in image coordinates to one that is expressed inlatitude-longitude coordinates.

If the number of files per image is zero, id will display an interactive window withmenu items for common GIS operations. Otherwise, id will perform a two-imageestimate of animal abundance as depicted by animal objects in the images. Note thatthe number of files actually listed is twice the number of files per image. The first setis for time-1 and the second is for time-2.

An image may consist of several files because file sizes of images that cover large areasand/or at high resolutions can become large. In these cases, image providers mayprovide each band as a separate GeoTiff file. Either way, if an image file is biggerthan 2 GB id may fail to read the entire file. Use the DOS command dir to find thenumber of bytes in a file.

The id software system assumes image files are in the ENVI Band Interleaved byPixel (.bip) format. The number of rows, columns, and bands are read from theassociated header file (filename.hdr). After downloading and installing the GeospatialData Abstraction Library (GDAL), use the batch file, gdal2envi.bat to translate aGeoTiff file to a file in ENVI format. See www.gdal.org for details on GDAL.

Specify the animal’s spectral signature. To discover this signature from an existingimage, use Microsoft’s PaintTM utility as follows:

1. Load image into Paint.

2. Click Color Picker in the Tools area of the toolbar.

3. Click in the middle of an animal object.

4. Click Edit Colors and read-off the RGB values.

19

Although these GIS tools are available in other free or lease-only software packages,they have been incorporated into id so that a user needs to learn only one, freesoftware system to perform ecosystem management analyses. See Haas (2011, ch. 5)for further discussion of this development goal of the id software system.

parse stories: Given a list of HTML-based story files, parses each story to create anEMAT actions entry. Execute the following steps to create EMAT entries.

1. Create a GoogleTM account and then create news alerts for a set of desiredkeyword phrases. Have these alerts sent to a mailbox.

2. Read each alert email. If a story seems relevant, open the story’s link and write itto a file as an HTML-only file type (“webpage, HTML only” in Internet ExplorerTM.Use a filename of sn.htm where n is a number, e.g. s1.htm s2.htm etc.

3. Prepare the id input file by listing the files to be read by entering the filenameprefix, postfix, the number of files to be read, the starting DAN, and the filecontaining group names in the vernacular, e.g.

parse stories(s htm 10 866 eastafgroups.dat)

to read 10 stories contained in the files s1.htm s2.htm ... s10.htm with actionsbeing given DAN values starting with the number 866.

4. Add the action entries written to the output file (usually shell.out) to the actionsdata base, e.g. eastafacts.dat.

5. The collection of news stories with all HTML markup tags removed will becontained in a file named dansntom.dat where n is the starting DAN, and m isthe ending dan in the file, respectively. In this file, each new story has a headerline of the form

STORY: ——– start DAN= n end DAN= m ————-

Stories for which the relation’s parsing algorithm failed are written to the file parse-failed.dat.

rdbms: builds or updates a relational database of political-ecological actions.

read NWS data: reads United States National Weather Service data.

compute risks: computes the risk of an animal going extinct using temporal output of astochastic abundance model.

find product themes: finds clusters of themes associated with a product being discussedin a data set of social media posts.

20

6.2 Relation for the describe data qualifier

This qualifier requests descriptive statistics to be computed for each node in the data file.id output includes summary statistics on each such node and output files that supportgraphical displays of the data.

compare samples: compares n pairs of samples taken on the listed pairs of variables. Boot-strap tests for differences in median, interquartile range (IQR), skew, and kurtosisare reported.

6.3 Relations for the estimate qualifier

This qualifier requests parameter estimation via Consistency Analysis (see Haas (2011, chs.4 and 11)). Detailed statistical fit, and assumption-satisfaction diagnostics are written tothe report file.

fit logits: gives the Logit model nodes for which logit parameters are to be found thatresult in logit probabilities matching as close as possible the conditional probabilitieslisted in the .par file.

estimate nodes: gives the nodes whose parameters are to be estimated. All other param-eters in the ID are held at their initial values (contained in init-file name) during theestimation procedure. The # of MC realizations parameter will need to be set highenough so that small changes to model parameters during the optimization algorithmcause detectable changes to the objective function.

The parameters initsubstep1, initsubstep2, and maximize are boolean parameters thatcontrol which CA step or substep is executed.

When run type equals “plots only,” the run stops after graphics are created of theinitial solution. Setting this parameter to “converged solution” causes the Consis-tency Analysis optimization algorithm to run to convergence.

Direct search is used to find parameter estimates and hence can be computationallyexpensive. See Appendix B for a description of a procedure used in id that speedsup this computation when a cluster of computers is available.

When an ID is to be evaluated in id, MC simulation is used in lieu of exact summationof conditional probability values since this latter method is known to be NP-hard (seeCooper (1987)).

There are ways to verify that the # of MC realizations parameter has been set to alarge enough value. The first method is to try progressively larger values until changesto the parameters of the node that is furthest from the node whose parameters arebeing fitted cause changes to the objective function. The second method is as follows.Let m = # of MC realizations. Every joint event in the ID can be represented viathe recursive factorization. For example, in a 3-node ID wherein node 3 is a root

21

node, node 2 is influenced by node 3, and node 1 is influenced by nodes 3 and 2, thejoint event {x1, x2, x3} can be written:

P (X1 = x1, X2 = x2, X3 = x3) = P (X1 = x1|x2, x3)P (X2 = x2, X3 = x3)

= P (X1 = x1|x2, x3)P (X2 = x2|x3)P (X3 = x3).

With some programming, the method Jntprb.jntprb () contained in the source codefile Jntprb.java can be used to find the joint event with the smallest probability. Letthis smallest probability be pje. Then, to see on average, at least one realization ofthe joint event during the simulation m ≥ 1/pje. For example, in the above example,if all conditional probabilities are 0.01, m needs to be greater than or equal to 1/0.013

or 106. If all of the probabilities are instead 0.1, m would need to be greater than orequal to 103.

prediction skill: gives the nodes whose parameters are to be estimated – all other pa-rameters in the ID are held at their hypothesis values during the estimation procedure.Then, one-time-step ahead predictions are computed beginning at firsttme. The RootMean Squared Prediction Error (RMSPE) is computed for these true forecast errors(i.e., not cross-validation).

cross-validation: performs cross-validation on the observations in the data file frommin time to max time. If there is no “Time” node, the time values to the cross-validation relation are ignored.

find mpemp: finds the Most practical Ecosystem Management Plan (MPEMP). The MPEMPis an actions history that causes a set of desired or target ecosystem state values tobe produced by the ecosystem ID at a set of desired future time points. See Haasand Ferreira (2018).

find interdiction patrol route: finds a patrol route that maximizes the chance of in-terdicting poaching parties.

pursuit strategy: real-time computation of a pursuit’s next position to move to so as tomaximize the chances of catching a pursued poaching party.

reconstruct social network: reconstructs a social network using data on the links be-tween network members, and predictions of which such links may be censored. Then,computes centrality measures on this reconstructed network to identify the network’skey players.

6.4 Relations for the evaluate qualifier

This qualifier requests evaluation of an ID or an IntIDs model. If LOMAP/GLOMAP type nodesare part of the ID, The model’s parameters are estimated before the model is evaluated.

22

id interactions: id supports dynamic models of interacting IDs (an IntIDs model). EachID is solved for its optimal decision node from begin time to end time. Within thisinterval, time is incremented by an internal time step and then all IDs are solvedagain while taking into account the optimal decisions of other IDs that were com-puted one time step previously. id requires a master id language file that consists ofinfluence diagram words that specify the id language files of the constituent IDs.

evaluate nodes: compute output on these nodes only.

surface: computes a surface of the dependent node via LOMAP predictions over the pointsof a grid enclosed by the boundary file. Setting grid type to 1 produces a rectangulargrid, and a setting of 2 produces a hexagonal grid.

If pred option = 1, one-step-ahead prediction is performed, i.e., model fitting andprediction is based only those datum that are one step earlier in time than the timespecified by pred time. If pred option = 2, observations that are within the spatio-temporal cylinder and earlier, concurrent, or later than the prediction time are used(temporal interpolation).

volume: computes the total volume under a spatial surface. Currently, only a LOMAP-generated surface is available. This relation also computes an MC-based standarderror of the volume estimate. The pred option parameter is defined as above.

simulate MOC: simulates students interacting with a software system that manages a Mas-sive Online Course (MOC).

find author clusters: clusters documents written by students enrolled in a MOC inorder to detect plagiarisim. Plagiarism is suggested when the documents purportedlywritten by a student cluster into well-separated clusters.

6.5 Relations for the display qualifier

This qualifier constructs graphical displays.

map levels: specifies the integer values to use to draw a choropleth map.

xyplots: creates abscissa-ordinate plots.

plot graph: creates a PostScript file of the ID’s graph after computing node positions thatminimize the number of link crossings.

label regions: creates a PostScript file of all region boundaries and region labels.

overlay: computes and displays the fraction of each value of a discretely-valued spatialnode that is contained within each region.

display intervals: defines a grayscale using the given list of intervals.

23

interval labels: uses the given list of strings to label the grayscale legend.

plot surface: creates a grayscale display of a surface.

plot actions history: creates a plot of an actions history. Arguments are: plot type andactions history file. An actions history file has two record types: Record Type 1:Actions record. The format for this record is: “action” time, actor, action, “one,”“two,” or “three” (indicating ONE, TWO, or THREE targets), a comma, and thena comma-delimited list of targets.

Example:

2002.25 Kenya rural residents clear new land one,ecosystem

This procedure is necessary because target node values can be of the variety:

two,Kenya rural residents,Kenya pastoralists

which is a single string but indicates 2 targets.

Record Type 2: Pentad record. The format of this record is: “pentad” output action identifierinput action identifier output action time input action input actor DM-group output actiontarget.

6.6 Relation for the sensitivity analysis qualifier

This qualifier performs a sensitivity analysis.

assess nodes: gives within-ID lists of nodes whose parameters will be the subjects of thesensitivity analysis.

6.7 Relation for the mc hypothesis test qualifier

This qualifier performs a Monte Carlo hypothesis test.

nodes to estimate: specifies IDs and nodes within those IDs that may have their param-eters estimated during each subsample’s Consistency Analysis. For the listed IDs, theparameter files in the initial-values positions within the individual id language files,express the null hypothesis and are used to compute the test statistic value underthat hypothesis.

Say that the null hypothesis dictates that node A has specific parameter values listedin the associated initial-values parameter file. Be careful to exclude node A from thenodes-to-estimate list.

24

References

Cooper, G. F. (1987) Probabilistic Inference Using Belief Networks is NP Hard, ResearchReport KSL-87-27, Medical Computer Science Group, Stanford University.

Haas, T. C. (1995), “Local Prediction of a Spatio-Temporal Process with an Applicationto Wet Sulfate Deposition,” Journal of the American Statistical Association, 90(432):1189-1199.

—– (2001), “A Web-Based System for Public-Private Sector Collaborative Ecosystem Man-agement,” Stochastic Environmental Research and Risk Assessment, 15(2): 101-131.

—– (2002), “New Systems for Modeling, Estimating, and Predicting a Multivariate Spatio-Temporal Process,” Environmetrics, 13(4): 311-332.

—– (2004) “Ecosystem Management via Interacting Models of Political and EcologicalProcesses,” Animal Biodiversity and Conservation, 27(1): 231-245.www.bcn.es/museuciencies

—– (2011), Improving Natural Resource Management: Ecological and Political Models, a“Statistics in Practice” volume, cross-listed in the Environmental Management, Policyand Planning series, and the Environmental Economics and Politics series, Wiley-Blackwell, Oxford, U.K. ISBN: 978-0-470-66113-0.www.wiley.com/WileyCDA/Section/id-350698.html

—– (2018), “Automatic Acquisition and Sustainable Use of Political-Ecological Data,” DataScience Journal, 17, p.17. DOI: http://doi.org/10.5334/dsj-2018-017

—– and Ferreira, S. M. (2018), “Finding Politically Feasible Conservation Strategies: TheCase of Wildlife Trafficking,” Ecological Applications, 28(2): 473-494, DOI: 10.1002/eap.1662.

—–, Mowrer, H. T., and Shepperd, W. D. (1994), “Modeling Aspen Stand Growth with aTemporal Bayes Network,” Artificial Intelligence Applications, 8(1), 15-28.

Johnson, J. H. (1994), “Representation, Knowledge Elicitation and Mathematical Science,”(in) Artificial Intelligence in Mathematics, (eds.) J. H. Johnson, S. McKee, and A.Vella, Oxford: Clarendon Press: 313-328.

Klerer, M. (1991), Design of Very High-Level Computer Languages, 2nd edition, New York:McGraw-Hill.

Koster, J. T. A. (1996), “Markov Properties of Nonrecursive Causal Models,” The Annalsof Statistics, 24(5): 2148-2177.

—– (1997), “On the Validity of the Markov Interpretation of Path Diagrams of LinearStructural Equations Systems with Correlated Errors,” Erasmus University TechnicalReport EUR/FSW/97.03.01, Rotterdam: Erasmus University.

Lubinsky, D. J. (1990), “Integrating Statistical Theory with Statistical Databases,” Annalsof Mathematics and Artificial Intelligence, 2: 245-259.

25