Using Dictionaries to Manage Data Within a Modeling Framework System

A DIC file is a comma-delimited text file (see Figure 5 for example).  This highly organized, structured design was chosen because it can be easily translated into a variety of other formats such as databases, html, xml, etc.  The design is also compact and efficient for modeling purposes.

DICs are expressed as html tables in this document for ease of viewing.  While DICs can be hand-coded, it is easiest for most users of FRAMES to build DIC files using the software tools provided with the system.  Table 1 provides an example DIC, in this case, a Chemical Water Concentration DIC, which describes the parameters associated with chemicals in water.  Note that this is the same DIC file shown in Figure 5.

Example of a Dictionary File as a Comma-Delimited Text File
(Chemical Water Concentration Dictionary)

• Variable Count, Description, Name, Privilege, Version, Updated, Template
• 3, Dissolved chemical concentrations, ChemWaterConc, 1, 1, 0
• Dictionary Name, Dictionary Description, Dimension, DataType, PrimaryKey, Scalar, Minimum, Maximum, Measure, Unit, Stochastic, Preposition, Index 1, Index 2, Index 3, , , , ,
• RunInfo, The set of strings that describe this dataset, 1, STRING, FALSE, FALSE, 0, 0, , , FALSE, , , , , , , , ,
• TimePts, Concentration time point, 3, FLOAT, FALSE, FALSE, 0, 100000000, Time, yr, FALSE, , WaterConcLocation.Feature, ChemList.CASID, , , , , ,
• WaterConc, The dissolve-phase concentration associated with water, 3, FLOAT, FALSE, TRUE, 0, 1.00E+30, Mass/Volume, mg/L, TRUE, , WaterConcLocation.Feature, ChemList.CASID, ChemWaterConc.TimePts, , , , ,

Legend

Column Name	Meaning
S	Scalar
D	Dimensional size
U	Can uncertainty apply (is it stochastic)
K	Is the variable a key to others

Note how various associated parameters are shown in the indices column in the above example.  An indexed parameter that occurs in another DIC is shown as a hyperlink, with the first part of the link (for example, WaterConcLocation) indicating the name of the DIC, and the second part of the link (after the period, in this case, Feature) indicating the parameter name.  An indexed parameter that occurs within the same DIC is not hyperlinked (for example, the indexed parameter TimePts in the last row of the DIC is a parameter listed in the third row of the DIC).

Note also that the example DIC includes a legend describing certain columns.  The information in these columns tells FRAMES how to handle the various types of data described in the DICs.  The scalar column (S) tells FRAMES whether one value (Y) or more than one value (N) is associated with a variable for a particular set of indices.  The dimensional size column (D) tells FRAMES the number of index values it takes to recall the parameter's value from the data.  The uncertainty column (U) tells FRAMES whether the parameter can be varied with a stochastic distribution (Yes or No).  The key column (K) tells FRAMES whether the parameter has been designated by the user through one of the system data management tools (Yes or No) as a key parameter.  A key parameter is one that is critical to the analysis, generally the issue around which the assessment strategy is built.  For example, in an ecological assessment, a criticalorganism might be the most important parameter in the analysis and all analysis variables would be based onorganism (in other words, have an index on organism).

As Table 1 above also shows, some DICs cross-reference others (as illustrated by the "See Also:" notation under the table's legend).  Cross-referencing indicates DICs with parameters that are heavily associated on each other, for example, a list of chemicals (ChemList) and chemical concentrations in water (ChemWaterConc, the dictionary shown in Table 1).

As seen in the example figure and table, the DIC files describe a variety of data types.  Table 2 provides definitions of various data fields associated with DIC files.

FRAMES' DICs serve three main functions: to describe the system or its components (system DICs), to provide data specific to a particular module (module-specific DICs), and to provide information to multiple modules or transfer information between components (boundary condition DICs).  Note that when FRAMES itself is used as part of a larger system, system DICs would be analogous to module-specific DICs.  For this reason, DICs provided in the appendix to this document are noted as being either module or boundary condition.  This notation is located above the html table as a privilege (the function the DIC plays in FRAMES).  The following subsections provide additional detail on the various functions of DICs.

System DICs describe the system or its components.  Such DICs are maintained by the system.

One critical system DIC is the start-up DIC.  This DIC describes the information necessary to set up the FRAMES user interface, including

• System path and run name
• Formatting information such as font, color, size, etc.
• Screen and line colors for both background and foreground
• Interface flags indicating items such as visible logo name, visible identification, etc.
• Window size and location on the computer screen
• Domain information (the type of problem being modeled).

The dataset for the start-up DIC is initially populated with default settings, as installed with FRAMES.  However, the user can modify many settings through the customize option in the user interface.  Table 3 shows an example start-up DIC.

Legend

Column Name	Meaning
S	Scalar
D	Dimensional size
U	Can uncertainty apply (is it stochastic)
K	Is the variable a key to others

Another type of system DIC is the simulation DIC, which contains the necessary information to reproduce a particular conceptual model (the picture of the real-world problem being modeled).  This information includes model names and identification, dataset names and locations, model and database status, linkages, model locking information, and simulation comments (see Table 4 for an example).

Legend

Column Name	Meaning
S	Scalar
D	Dimensional size
U	Can uncertainty apply (is it stochastic)
K	Is the variable a key to others

Another type of system DIC is the conversion DIC, which allows units to be converted between modules in FRAMES.  Table 5 provides an example of a conversion DIC.

Legend

Column Name	Meaning
S	Scalar
D	Dimensional size
U	Can uncertainty apply (is it stochastic)
K	Is the variable a key to others

Another type of system DIC is the module properties DIC, which describes data on the component and its supporting infrastructure.  Such data might include the point of contact for additional information, module-specific and boundary condition DICs consumed and produced, and how the module fits into a modeling scheme.  This DIC is maintained by the system, but the corresponding dataset is populated by the developer when initially incorporating a component into FRAMES (see Table 6 for an example).

Legend

Column Name	Meaning
S	Scalar
D	Dimensional size
U	Can uncertainty apply (is it stochastic)
K	Is the variable a key to others

Module-specific DICs consist of information describing data required by a specific module to operate.  For some modules, these are data to be analyzed.  For other module-specific DICs, the data described allow the analysis to occur in a specific fashion.  For example, a sensitivity/uncertainty module (which analyzes which parameters more heavily influence the results of an analysis) requires the use of iterator DICs.  Iterator DICs define statistical information associated with the stochastic data; that is, data that can be varied to determine a parameter"s sensitivity or uncertainty.  FRAMES uses five types of iterator DICs:

• Seed DIC, which consists of information defining the starting seed number so that random numbers can be generated to allow the analysis to vary a parameter (Table 7).
• Iteration DIC, which consists of information defining the current iteration of the simulation (Table 8).
• Sampled Values DIC, which consists of information defining the inputs that are being sampled as stochastic and available for sampling (Table 9).
• Summary Values DIC, which consists of information defining the outputs that are summarized as part of the statistical results (Table 10).
• Stochastic DIC, which consists of information defining the distribution and attributes associated with the stochastic parameters (Table 11).

Boundary condition dictionaries provide information to multiple modules (see Table 12 for an example) or transfer information between components.  Two important types of boundary condition DICs are as follows:

• Model DIC, which describes information that is passed from a producing model to a consuming model.  These DICs represent the output results from a model (see Table 13 for an example) and must be complete (i.e., no missing data).
• Database DIC, which contains information associated with the mapping of data between a database and the system.  Note that a database DIC would look similar to a model DIC except that the dataset for a database DIC does not have to be complete (i.e., some data can be missing but a method must be supplied to allow the user to provide these data during analysis of the problem being modeled).