whatIf? Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**Found this stuff in the create() tool documentation. We can trim as required.**

List the ways set informants can be defined:
  * manually in Documenter
  * copy-and-paste from one Documenter .dmm file to another 
  * from an informant definition file within Documenter (set or category)
    * sets definition files can be created from the source data with a TOOL script
 
Sequence informants are defined in the Documenter dialogue box. 

====== Creating a Set Object ======

A set is a type of object that contains a list of elements that may be used to represent a class to which another object
may belong or a list of characteristics an object may possess. A set is commonly used as an informant to another
object such as an array. For example, the set sex is an object that contains two elements, males and females which
define a class to which a population object may belong. The following is the general syntax used to create a set
object:

<code>
A[] = create (;object=set, {dataFile=fileName,
data=dataStr,
data1="name1 .. namem",...,
dataj="namen .. namez",
elem1="name1 desc1",...,
elemn="namen descn"},
{desc=descrStr})
</code>

===== Specifying the Object Type =====

The object type is specified when the object is created. The mandatory parameter object is used to specify an object
type of set:

<code>
object=set
</code>

==== Examples: ====

<code>
crop[] = create (; object=set, data="wheat corn barley")
</code>

This statement is used to create a set object.

===== Specifying the Object Data from a File =====

Set object data that defines the elements of the set must be specified when the object is created. This data can come
from a file that contains the data or directly from a parameter. The optional parameter dataFile is used to specify set
object data from a file in the current working directory:
dataFile=fileName
where fileName is a file containing the set object data. This file must have the following format:

<file>
...
namei desci
...
</file>

where namei is a single word alphanumeric string that is the name of the ith element of the set object and
desci is a multiple word alphanumeric string that is the description of the ith element of the set
object. The element name and description must be separated by tabs or spaces, the description
must be enclosed within "quotes" and each line must end with a carriage return. The number of
lines containing name and description pairs will determine the extent of the set object.
The file may contain any number of comment lines which begin with the character !.

==== Examples: ====
<code>
crop[] = create (; object=set, dataFile=crop.txt)
</code>

where 'crop.txt' is a file containing:

<file>
! the set 'crop'
wheat "wheat seed crop"
corn "corn seed crop"
barley "barley seed crop"
</file>

Creates the set object, ''crop[]'', containing the elements:{wheat, corn, barley}

===== Specifying the Object Data from a Parameter =====

Set object data can be specified from a parameter when the object is created. The optional parameter data is used to
specify set object data directly:

<code>
data="name1 name2 ... namem"
</code>

where namei is a single word alphanumeric string that is the name of the element of the set object. The list of
element names must be separated by tabs or spaces and be enclosed within "quotes". The number of element
names specified will determine the extent of the set object. The elements of a set object created
using this parameter only have names and do not have descriptions.

==== Examples: ====

crop[] = create (; object=set, data="wheat corn barley")
Creates the set object, crop[], containing the elements:{wheat, corn, barley}
Specifying the Object Data from Multiple Parameters
Set object data can also be specified from multiple parameters when the object is created. The optional parameter
datai is used to specify set object data directly:

<code>
data1="name1 name2 ... namem"
...
dataj="namen nameo ... namez"
</code>

where namei is a single word alphanumeric string that is the name of the element of the set object. The list of
element names must be separated by tabs or spaces and be enclosed within "quotes". The number of element
names specified will determine the extent of the set object. The elements of a set object created
using this parameter only have names and do not have descriptions.

==== Examples: ====

crop[] = create( ; object=set, data1="wheat", data2="corn barley")
Creates the set object, crop[], containing the elements: {wheat, corn, barley}
Set object data having both element names and descriptions can also be specified from multiple parameters when the
object is created. The optional parameter elemi can used to specify set object data directly:

<code>
elem1="namei desci"
...
elemj="namej descj"
</code>

where namei is a single word alphanumeric string that is the name of the ith element of the set object and desci is a
multiple word alphanumeric string that is the description of the ith element of the set object. The element
name and description must be separated by tabs or spaces and be enclosed within "quotes". The number of
elemi parameters specified will determine the extent of the set object.

<code>
crop[] = create (; object=set, \
elem1="wheatwheat seed crop", \
elem2="corncorn seed crop", \
elem3="barleybarley seed crop")
</code>

Creates the set object, crop[], containing the elements with descriptions:
{wheat wheat seed crop
corn corn seed crop
barley barley seed crop}
===== 
Specifying an Object Description =====

The description for a set object can be specified from a parameter when the object is created. If a description is not
specified, the set object is created with a description of the object statement that created the object. The optional
parameter desc is used to specify a set object description:

<code>
desc=descString
</code>

where descString is an alphanumeric string.

==== Examples: ====

<code>
sex[] = create (; object=set, data="male female", desc="gender")
</code>

The statement creates a set object with a description of "gender":

===== Element names - characters to avoid =====

:!: The comma "," and period "." characters must not be used used in element names (they cause issues with Documenter and category definitions).

It is highly reccomended that whitespace and other non-alphanumeric characters be avoided in element names.

[Describe the searchElemName and replaceElemName parameters in the create tool. Provide examples.] FIXME

<code>
localinformant employmentSector_d[] = create (; object=set, delimiter=",", \
	allowDuplicate=off, \
	elemNamesFromColNum=1, firstLine=1, \
	searchElemName1=",", replaceElemName1="", \
	searchElemName2=".", replaceElemName2="_", \
	searchElemName3="&", replaceElemName3="and", \
	searchElemName4="/", replaceElemName4="_", \
	searchElemName5="(", replaceElemName5="", \
	searchElemName6=")", replaceElemName6="", \
	searchElemName7="]", replaceElemName7="", \
	searchElemName8="[", replaceElemName8="", \
	searchElemName9="-", replaceElemName9="_", \
	searchElemName10="'", replaceElemName10="", \
	searchElemName11="$", replaceElemName11="dlr", \
	searchElemName12="%", replaceElemName12="pct", \
	searchElemName13=":", replaceElemName13="", \
	stripLeadingWhiteSpace=off, \
	replaceWhiteSpaceInElemName="_" , \
	file=$fileName)
</code>

====== Creating a Category Object ======

===== Specifying the Category Definition from Parameters =====

Example:

<code>
localinformant egtCOfte_nr[] = create (; object=category, \
	desc="elecGenTech category of fuelTypeElec", \
	groups = elecGenTech, \
	members = fuelTypeElec, \
	delimiter = ",", \
	"combSteamSF" = "coal,heavyOil,petroleumCoke,naturalGas", \
	"combTurbineSF" = "coal,heavyOil,petroleumCoke,naturalGas", \
	"combineCycleSF" = "coal,heavyOil,petroleumCoke,naturalGas", \
	"nucLWSteam" = "urainium", \
	"nucHWSteam" = "urainium", \
	"combSteamMF" = "multiFuel", \
	"combTurbineMF" = "multiFuel", \
	"combineCycleMF" = "multiFuel", \
	"industrialSector" = "nonSpecifiedFuel", \
	"commercialSector" = "nonSpecifiedFuel")
</code>
whatIf? Wiki

User Tools

Site Tools

Page Tools
